@browserbasehq/orca 3.5.0-preview.1 → 3.5.1-preview.0

package/dist/cjs/lib/v3/dom/locatorScripts/xpathResolver.js

@@ -34,7 +34,11 @@ function resolveXPathAtIndex(rawXp, index, options) {
         return composed[targetIndex] ?? null;
     }
     const composed = resolveXPathComposedMatches(xp, shadowCtx.getClosedRoot);
-    return composed[targetIndex] ?? null;
+    if (composed.length > 0) {
+        return composed[targetIndex] ?? null;
+    }
+    const shadowHopMatches = resolveStagehandShadowHopMatches(xp, shadowCtx.getClosedRoot);
+    return shadowHopMatches[targetIndex] ?? null;
 }
 function countXPathMatches(rawXp, options) {
     const xp = normalizeXPath(rawXp);
@@ -51,7 +55,10 @@ function countXPathMatches(rawXp, options) {
             return count.count;
         return resolveXPathComposedMatches(xp, shadowCtx?.getClosedRoot).length;
     }
-    return resolveXPathComposedMatches(xp, shadowCtx.getClosedRoot).length;
+    const composedCount = resolveXPathComposedMatches(xp, shadowCtx.getClosedRoot).length;
+    if (composedCount > 0)
+        return composedCount;
+    return resolveStagehandShadowHopMatches(xp, shadowCtx.getClosedRoot).length;
 }
 function resolveXPathComposedMatches(rawXp, getClosedRoot) {
     const xp = normalizeXPath(rawXp);
@@ -61,15 +68,11 @@ function resolveXPathComposedMatches(rawXp, getClosedRoot) {
     if (!steps.length)
         return [];
     const closedRoot = getClosedRoot ?? null;
-    let current = [
-        document,
-    ];
+    let current = [document];
     for (const step of steps) {
         const next = [];
         const seen = new Set();
         for (const root of current) {
-            if (!root)
-                continue;
             const pool = step.axis === "child"
                 ? composedChildren(root, closedRoot)
                 : composedDescendants(root, closedRoot);
@@ -90,6 +93,43 @@ function resolveXPathComposedMatches(rawXp, getClosedRoot) {
     }
     return current;
 }
+function resolveStagehandShadowHopMatches(rawXp, getClosedRoot) {
+    const xp = normalizeXPath(rawXp);
+    if (!xp)
+        return [];
+    const steps = (0, xpathParser_js_1.parseXPathSteps)(xp);
+    if (!steps.some((step, index) => step.axis === "desc" && index > 0)) {
+        return [];
+    }
+    const closedRoot = getClosedRoot ?? null;
+    let current = [document];
+    for (let i = 0; i < steps.length; i += 1) {
+        const step = steps[i];
+        const next = [];
+        const seen = new Set();
+        for (const root of current) {
+            const pool = step.axis === "child"
+                ? domChildren(root)
+                : i === 0
+                    ? composedDescendants(root, closedRoot)
+                    : shadowRootChildren(root, closedRoot);
+            if (!pool.length)
+                continue;
+            const tagMatches = pool.filter((candidate) => matchesTag(candidate, step));
+            const matches = (0, xpathParser_js_1.applyPredicates)(tagMatches, step.predicates);
+            for (const candidate of matches) {
+                if (!seen.has(candidate)) {
+                    seen.add(candidate);
+                    next.push(candidate);
+                }
+            }
+        }
+        if (!next.length)
+            return [];
+        current = next;
+    }
+    return current;
+}
 function matchesTag(element, step) {
     if (step.tag === "*")
         return true;
@@ -136,8 +176,6 @@ function getShadowContext() {
 }
 function composedChildren(node, getClosedRoot) {
     const out = [];
-    if (!node)
-        return out;
     if (node instanceof Document) {
         if (node.documentElement)
             out.push(node.documentElement);
@@ -161,13 +199,44 @@ function composedChildren(node, getClosedRoot) {
     }
     return out;
 }
+function domChildren(node) {
+    const out = [];
+    if (node instanceof Document) {
+        if (node.documentElement)
+            out.push(node.documentElement);
+        return out;
+    }
+    if (node instanceof ShadowRoot || node instanceof DocumentFragment) {
+        out.push(...Array.from(node.children ?? []));
+        return out;
+    }
+    if (node instanceof Element) {
+        out.push(...Array.from(node.children ?? []));
+        return out;
+    }
+    return out;
+}
+function shadowRootChildren(node, getClosedRoot) {
+    const out = [];
+    if (!(node instanceof Element))
+        return out;
+    const open = node.shadowRoot;
+    if (open)
+        out.push(...Array.from(open.children ?? []));
+    if (getClosedRoot) {
+        const closed = getClosedRoot(node);
+        if (closed)
+            out.push(...Array.from(closed.children ?? []));
+    }
+    return out;
+}
 function composedDescendants(node, getClosedRoot) {
     const out = [];
     const seen = new Set();
     const stack = [...composedChildren(node, getClosedRoot)].reverse();
     while (stack.length) {
         const next = stack.pop();
-        if (!next || seen.has(next))
+        if (seen.has(next))
             continue;
         seen.add(next);
         out.push(next);

package/dist/cjs/lib/v3/dom/locatorScripts/xpathResolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"xpathResolver.js","sourceRoot":"","sources":["../../../../../../lib/v3/dom/locatorScripts/xpathResolver.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  applyPredicates,\n  parseXPathSteps,\n  type XPathStep,\n} from \"./xpathParser.js\";\n\ntype ClosedRootGetter = (host: Element) => ShadowRoot | null;\n\nexport type XPathResolveOptions = {\n  pierceShadow?: boolean;\n};\n\ntype ShadowContext = {\n  getClosedRoot: ClosedRootGetter | null;\n  hasShadow: boolean;\n};\n\nconst normalizeXPath = (selector: string): string => {\n  const raw = String(selector ?? \"\").trim();\n  if (!raw) return \"\";\n  return raw.replace(/^xpath=/i, \"\").trim();\n};\n\nexport function resolveXPathFirst(\n  rawXp: string,\n  options?: XPathResolveOptions,\n): Element | null {\n  return resolveXPathAtIndex(rawXp, 0, options);\n}\n\nexport function resolveXPathAtIndex(\n  rawXp: string,\n  index: number,\n  options?: XPathResolveOptions,\n): Element | null {\n  if (!Number.isFinite(index) || index < 0) return null;\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return null;\n\n  const targetIndex = Math.floor(index);\n  const pierceShadow = options?.pierceShadow !== false;\n  const shadowCtx = pierceShadow ? getShadowContext() : null;\n\n  if (!pierceShadow) {\n    return resolveNativeAtIndexWithError(xp, targetIndex).value;\n  }\n\n  if (!shadowCtx?.hasShadow) {\n    const native = resolveNativeAtIndexWithError(xp, targetIndex);\n    if (!native.error) return native.value;\n    const composed = resolveXPathComposedMatches(xp, shadowCtx?.getClosedRoot);\n    return composed[targetIndex] ?? null;\n  }\n\n  const composed = resolveXPathComposedMatches(xp, shadowCtx.getClosedRoot);\n  return composed[targetIndex] ?? null;\n}\n\nexport function countXPathMatches(\n  rawXp: string,\n  options?: XPathResolveOptions,\n): number {\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return 0;\n\n  const pierceShadow = options?.pierceShadow !== false;\n  const shadowCtx = pierceShadow ? getShadowContext() : null;\n\n  if (!pierceShadow) {\n    return resolveNativeCountWithError(xp).count;\n  }\n\n  if (!shadowCtx?.hasShadow) {\n    const count = resolveNativeCountWithError(xp);\n    if (!count.error) return count.count;\n    return resolveXPathComposedMatches(xp, shadowCtx?.getClosedRoot).length;\n  }\n\n  return resolveXPathComposedMatches(xp, shadowCtx.getClosedRoot).length;\n}\n\nexport function resolveXPathComposedMatches(\n  rawXp: string,\n  getClosedRoot?: ClosedRootGetter | null,\n): Element[] {\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return [];\n\n  const steps = parseXPathSteps(xp);\n  if (!steps.length) return [];\n\n  const closedRoot = getClosedRoot ?? null;\n\n  let current: Array<Document | Element | ShadowRoot | DocumentFragment> = [\n    document,\n  ];\n\n  for (const step of steps) {\n    const next: Element[] = [];\n    const seen = new Set<Element>();\n\n    for (const root of current) {\n      if (!root) continue;\n      const pool =\n        step.axis === \"child\"\n          ? composedChildren(root, closedRoot)\n          : composedDescendants(root, closedRoot);\n      if (!pool.length) continue;\n\n      const tagMatches = pool.filter((candidate) =>\n        matchesTag(candidate, step),\n      );\n      const matches = applyPredicates(tagMatches, step.predicates);\n\n      for (const candidate of matches) {\n        if (!seen.has(candidate)) {\n          seen.add(candidate);\n          next.push(candidate);\n        }\n      }\n    }\n\n    if (!next.length) return [];\n    current = next;\n  }\n\n  return current as Element[];\n}\n\nfunction matchesTag(element: Element, step: XPathStep): boolean {\n  if (step.tag === \"*\") return true;\n  return element.localName === step.tag;\n}\n\nfunction getShadowContext(): ShadowContext {\n  const backdoor = window.__stagehandV3__;\n  const getClosedRoot: ClosedRootGetter | null =\n    backdoor && typeof backdoor.getClosedRoot === \"function\"\n      ? (host: Element): ShadowRoot | null => {\n          try {\n            return backdoor.getClosedRoot(host) ?? null;\n          } catch {\n            return null;\n          }\n        }\n      : null;\n\n  let hasShadow = false;\n  try {\n    if (backdoor && typeof backdoor.stats === \"function\") {\n      const stats = backdoor.stats();\n      hasShadow = (stats?.open ?? 0) > 0 || (stats?.closed ?? 0) > 0;\n    }\n  } catch {\n    // ignore stats errors\n  }\n\n  if (!hasShadow) {\n    try {\n      const walker = document.createTreeWalker(\n        document,\n        NodeFilter.SHOW_ELEMENT,\n      );\n      while (walker.nextNode()) {\n        const el = walker.currentNode as Element;\n        if (el.shadowRoot) {\n          hasShadow = true;\n          break;\n        }\n      }\n    } catch {\n      // ignore scan errors\n    }\n  }\n\n  return { getClosedRoot, hasShadow };\n}\n\nfunction composedChildren(\n  node: Node | null | undefined,\n  getClosedRoot: ClosedRootGetter | null,\n): Element[] {\n  const out: Element[] = [];\n  if (!node) return out;\n\n  if (node instanceof Document) {\n    if (node.documentElement) out.push(node.documentElement);\n    return out;\n  }\n\n  if (node instanceof ShadowRoot || node instanceof DocumentFragment) {\n    out.push(...Array.from(node.children ?? []));\n    return out;\n  }\n\n  if (node instanceof Element) {\n    out.push(...Array.from(node.children ?? []));\n    const open = node.shadowRoot;\n    if (open) out.push(...Array.from(open.children ?? []));\n    if (getClosedRoot) {\n      const closed = getClosedRoot(node);\n      if (closed) out.push(...Array.from(closed.children ?? []));\n    }\n    return out;\n  }\n\n  return out;\n}\n\nfunction composedDescendants(\n  node: Node | null | undefined,\n  getClosedRoot: ClosedRootGetter | null,\n): Element[] {\n  const out: Element[] = [];\n  const seen = new Set<Element>();\n  const stack = [...composedChildren(node, getClosedRoot)].reverse();\n\n  while (stack.length) {\n    const next = stack.pop();\n    if (!next || seen.has(next)) continue;\n    seen.add(next);\n    out.push(next);\n\n    const children = composedChildren(next, getClosedRoot);\n    for (let i = children.length - 1; i >= 0; i -= 1) {\n      stack.push(children[i]!);\n    }\n  }\n\n  return out;\n}\n\nfunction resolveNativeAtIndexWithError(\n  xp: string,\n  index: number,\n): { value: Element | null; error: boolean } {\n  try {\n    const snapshot = document.evaluate(\n      xp,\n      document,\n      null,\n      XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n      null,\n    );\n    return {\n      value: snapshot.snapshotItem(index) as Element | null,\n      error: false,\n    };\n  } catch {\n    return { value: null, error: true };\n  }\n}\n\nfunction resolveNativeCountWithError(xp: string): {\n  count: number;\n  error: boolean;\n} {\n  try {\n    const snapshot = document.evaluate(\n      xp,\n      document,\n      null,\n      XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n      null,\n    );\n    return { count: snapshot.snapshotLength, error: false };\n  } catch {\n    return { count: 0, error: true };\n  }\n}\n"]}
+{"version":3,"file":"xpathResolver.js","sourceRoot":"","sources":["../../../../../../lib/v3/dom/locatorScripts/xpathResolver.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  applyPredicates,\n  parseXPathSteps,\n  type XPathStep,\n} from \"./xpathParser.js\";\n\ntype ClosedRootGetter = (host: Element) => ShadowRoot | null;\ntype TraversalRoot = Document | Element | ShadowRoot | DocumentFragment;\n\nexport type XPathResolveOptions = {\n  pierceShadow?: boolean;\n};\n\ntype ShadowContext = {\n  getClosedRoot: ClosedRootGetter | null;\n  hasShadow: boolean;\n};\n\nconst normalizeXPath = (selector: string): string => {\n  const raw = String(selector ?? \"\").trim();\n  if (!raw) return \"\";\n  return raw.replace(/^xpath=/i, \"\").trim();\n};\n\nexport function resolveXPathFirst(\n  rawXp: string,\n  options?: XPathResolveOptions,\n): Element | null {\n  return resolveXPathAtIndex(rawXp, 0, options);\n}\n\nexport function resolveXPathAtIndex(\n  rawXp: string,\n  index: number,\n  options?: XPathResolveOptions,\n): Element | null {\n  if (!Number.isFinite(index) || index < 0) return null;\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return null;\n\n  const targetIndex = Math.floor(index);\n  const pierceShadow = options?.pierceShadow !== false;\n  const shadowCtx = pierceShadow ? getShadowContext() : null;\n\n  if (!pierceShadow) {\n    return resolveNativeAtIndexWithError(xp, targetIndex).value;\n  }\n\n  if (!shadowCtx?.hasShadow) {\n    const native = resolveNativeAtIndexWithError(xp, targetIndex);\n    if (!native.error) return native.value;\n    const composed = resolveXPathComposedMatches(xp, shadowCtx?.getClosedRoot);\n    return composed[targetIndex] ?? null;\n  }\n\n  const composed = resolveXPathComposedMatches(xp, shadowCtx.getClosedRoot);\n  if (composed.length > 0) {\n    return composed[targetIndex] ?? null;\n  }\n\n  const shadowHopMatches = resolveStagehandShadowHopMatches(\n    xp,\n    shadowCtx.getClosedRoot,\n  );\n  return shadowHopMatches[targetIndex] ?? null;\n}\n\nexport function countXPathMatches(\n  rawXp: string,\n  options?: XPathResolveOptions,\n): number {\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return 0;\n\n  const pierceShadow = options?.pierceShadow !== false;\n  const shadowCtx = pierceShadow ? getShadowContext() : null;\n\n  if (!pierceShadow) {\n    return resolveNativeCountWithError(xp).count;\n  }\n\n  if (!shadowCtx?.hasShadow) {\n    const count = resolveNativeCountWithError(xp);\n    if (!count.error) return count.count;\n    return resolveXPathComposedMatches(xp, shadowCtx?.getClosedRoot).length;\n  }\n\n  const composedCount = resolveXPathComposedMatches(\n    xp,\n    shadowCtx.getClosedRoot,\n  ).length;\n  if (composedCount > 0) return composedCount;\n\n  return resolveStagehandShadowHopMatches(xp, shadowCtx.getClosedRoot).length;\n}\n\nexport function resolveXPathComposedMatches(\n  rawXp: string,\n  getClosedRoot?: ClosedRootGetter | null,\n): Element[] {\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return [];\n\n  const steps = parseXPathSteps(xp);\n  if (!steps.length) return [];\n\n  const closedRoot = getClosedRoot ?? null;\n\n  let current: TraversalRoot[] = [document];\n\n  for (const step of steps) {\n    const next: Element[] = [];\n    const seen = new Set<Element>();\n\n    for (const root of current) {\n      const pool =\n        step.axis === \"child\"\n          ? composedChildren(root, closedRoot)\n          : composedDescendants(root, closedRoot);\n      if (!pool.length) continue;\n\n      const tagMatches = pool.filter((candidate) =>\n        matchesTag(candidate, step),\n      );\n      const matches = applyPredicates(tagMatches, step.predicates);\n\n      for (const candidate of matches) {\n        if (!seen.has(candidate)) {\n          seen.add(candidate);\n          next.push(candidate);\n        }\n      }\n    }\n\n    if (!next.length) return [];\n    current = next;\n  }\n\n  return current as Element[];\n}\n\nfunction resolveStagehandShadowHopMatches(\n  rawXp: string,\n  getClosedRoot?: ClosedRootGetter | null,\n): Element[] {\n  const xp = normalizeXPath(rawXp);\n  if (!xp) return [];\n\n  const steps = parseXPathSteps(xp);\n  if (!steps.some((step, index) => step.axis === \"desc\" && index > 0)) {\n    return [];\n  }\n\n  const closedRoot = getClosedRoot ?? null;\n  let current: TraversalRoot[] = [document];\n\n  for (let i = 0; i < steps.length; i += 1) {\n    const step = steps[i]!;\n    const next: Element[] = [];\n    const seen = new Set<Element>();\n\n    for (const root of current) {\n      const pool =\n        step.axis === \"child\"\n          ? domChildren(root)\n          : i === 0\n            ? composedDescendants(root, closedRoot)\n            : shadowRootChildren(root, closedRoot);\n      if (!pool.length) continue;\n\n      const tagMatches = pool.filter((candidate) =>\n        matchesTag(candidate, step),\n      );\n      const matches = applyPredicates(tagMatches, step.predicates);\n\n      for (const candidate of matches) {\n        if (!seen.has(candidate)) {\n          seen.add(candidate);\n          next.push(candidate);\n        }\n      }\n    }\n\n    if (!next.length) return [];\n    current = next;\n  }\n\n  return current as Element[];\n}\n\nfunction matchesTag(element: Element, step: XPathStep): boolean {\n  if (step.tag === \"*\") return true;\n  return element.localName === step.tag;\n}\n\nfunction getShadowContext(): ShadowContext {\n  const backdoor = window.__stagehandV3__;\n  const getClosedRoot: ClosedRootGetter | null =\n    backdoor && typeof backdoor.getClosedRoot === \"function\"\n      ? (host: Element): ShadowRoot | null => {\n          try {\n            return backdoor.getClosedRoot(host) ?? null;\n          } catch {\n            return null;\n          }\n        }\n      : null;\n\n  let hasShadow = false;\n  try {\n    if (backdoor && typeof backdoor.stats === \"function\") {\n      const stats = backdoor.stats();\n      hasShadow = (stats?.open ?? 0) > 0 || (stats?.closed ?? 0) > 0;\n    }\n  } catch {\n    // ignore stats errors\n  }\n\n  if (!hasShadow) {\n    try {\n      const walker = document.createTreeWalker(\n        document,\n        NodeFilter.SHOW_ELEMENT,\n      );\n      while (walker.nextNode()) {\n        const el = walker.currentNode as Element;\n        if (el.shadowRoot) {\n          hasShadow = true;\n          break;\n        }\n      }\n    } catch {\n      // ignore scan errors\n    }\n  }\n\n  return { getClosedRoot, hasShadow };\n}\n\nfunction composedChildren(\n  node: TraversalRoot,\n  getClosedRoot: ClosedRootGetter | null,\n): Element[] {\n  const out: Element[] = [];\n\n  if (node instanceof Document) {\n    if (node.documentElement) out.push(node.documentElement);\n    return out;\n  }\n\n  if (node instanceof ShadowRoot || node instanceof DocumentFragment) {\n    out.push(...Array.from(node.children ?? []));\n    return out;\n  }\n\n  if (node instanceof Element) {\n    out.push(...Array.from(node.children ?? []));\n    const open = node.shadowRoot;\n    if (open) out.push(...Array.from(open.children ?? []));\n    if (getClosedRoot) {\n      const closed = getClosedRoot(node);\n      if (closed) out.push(...Array.from(closed.children ?? []));\n    }\n    return out;\n  }\n\n  return out;\n}\n\nfunction domChildren(node: TraversalRoot): Element[] {\n  const out: Element[] = [];\n\n  if (node instanceof Document) {\n    if (node.documentElement) out.push(node.documentElement);\n    return out;\n  }\n\n  if (node instanceof ShadowRoot || node instanceof DocumentFragment) {\n    out.push(...Array.from(node.children ?? []));\n    return out;\n  }\n\n  if (node instanceof Element) {\n    out.push(...Array.from(node.children ?? []));\n    return out;\n  }\n\n  return out;\n}\n\nfunction shadowRootChildren(\n  node: TraversalRoot,\n  getClosedRoot: ClosedRootGetter | null,\n): Element[] {\n  const out: Element[] = [];\n  if (!(node instanceof Element)) return out;\n\n  const open = node.shadowRoot;\n  if (open) out.push(...Array.from(open.children ?? []));\n  if (getClosedRoot) {\n    const closed = getClosedRoot(node);\n    if (closed) out.push(...Array.from(closed.children ?? []));\n  }\n\n  return out;\n}\n\nfunction composedDescendants(\n  node: TraversalRoot,\n  getClosedRoot: ClosedRootGetter | null,\n): Element[] {\n  const out: Element[] = [];\n  const seen = new Set<Element>();\n  const stack = [...composedChildren(node, getClosedRoot)].reverse();\n\n  while (stack.length) {\n    const next = stack.pop()!;\n    if (seen.has(next)) continue;\n    seen.add(next);\n    out.push(next);\n\n    const children = composedChildren(next, getClosedRoot);\n    for (let i = children.length - 1; i >= 0; i -= 1) {\n      stack.push(children[i]!);\n    }\n  }\n\n  return out;\n}\n\nfunction resolveNativeAtIndexWithError(\n  xp: string,\n  index: number,\n): { value: Element | null; error: boolean } {\n  try {\n    const snapshot = document.evaluate(\n      xp,\n      document,\n      null,\n      XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n      null,\n    );\n    return {\n      value: snapshot.snapshotItem(index) as Element | null,\n      error: false,\n    };\n  } catch {\n    return { value: null, error: true };\n  }\n}\n\nfunction resolveNativeCountWithError(xp: string): {\n  count: number;\n  error: boolean;\n} {\n  try {\n    const snapshot = document.evaluate(\n      xp,\n      document,\n      null,\n      XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n      null,\n    );\n    return { count: snapshot.snapshotLength, error: false };\n  } catch {\n    return { count: 0, error: true };\n  }\n}\n"]}

package/dist/cjs/lib/v3/index.d.ts

@@ -69,7 +69,7 @@ declare const StagehandDefault: {
     Api: typeof PublicApi.Api;
     AISdkClient: typeof PublicApi.AISdkClient;
     CustomOpenAIClient: typeof PublicApi.CustomOpenAIClient;
-    AVAILABLE_CUA_MODELS: readonly ["openai/gpt-5.4", "openai/gpt-5.4-mini", "openai/gpt-5.5", "openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
+    AVAILABLE_CUA_MODELS: readonly ["openai/gpt-5.4", "openai/gpt-5.4-mini", "openai/gpt-5.5", "openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-opus-4-8", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
     StagehandAPIError: typeof PublicApi.StagehandAPIError;
     StagehandAPIUnauthorizedError: typeof PublicApi.StagehandAPIUnauthorizedError;
     StagehandHttpError: typeof PublicApi.StagehandHttpError;
@@ -123,6 +123,7 @@ declare const StagehandDefault: {
     UnsupportedModelError: typeof PublicApi.UnsupportedModelError;
     UnsupportedModelProviderError: typeof PublicApi.UnsupportedModelProviderError;
     UnsupportedAISDKModelProviderError: typeof PublicApi.UnsupportedAISDKModelProviderError;
+    StagehandUnsupportedBrowserFeatureError: typeof PublicApi.StagehandUnsupportedBrowserFeatureError;
     InvalidAISDKModelFormatError: typeof PublicApi.InvalidAISDKModelFormatError;
     StagehandNotInitializedError: typeof PublicApi.StagehandNotInitializedError;
     BrowserbaseSessionNotFoundError: typeof PublicApi.BrowserbaseSessionNotFoundError;

package/dist/cjs/lib/v3/llm/LLMProvider.js

@@ -60,13 +60,29 @@ const AISDKProvidersWithAPIKey = {
     gateway: ai_1.createGateway,
 };
 function toAISDKClientOptions(subProvider, clientOptions) {
-    if (!clientOptions || subProvider !== "vertex") {
+    if (!clientOptions) {
+        return clientOptions;
+    }
+    const { auth, providerOptions, apiKey, ...rest } = clientOptions;
+    const apiKeyOption = !auth && apiKey ? { apiKey } : {};
+    if (subProvider === "azure") {
+        const azureOptions = providerOptions?.azure;
+        return {
+            ...rest,
+            ...apiKeyOption,
+            ...(azureOptions ?? {}),
+            ...(auth?.type === "azureEntraId"
+                ? { tokenProvider: async () => auth.token }
+                : {}),
+        };
+    }
+    if (subProvider !== "vertex") {
         return clientOptions;
     }
-    const { auth, providerOptions, ...rest } = clientOptions;
     const vertexOptions = providerOptions?.vertex;
     return {
         ...rest,
+        ...apiKeyOption,
         ...(vertexOptions ?? {}),
         ...(auth?.type === "googleServiceAccount"
             ? {

package/dist/cjs/lib/v3/llm/LLMProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMProvider.js","sourceRoot":"","sources":["../../../../../lib/v3/llm/LLMProvider.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LanguageModelV2Middleware } from \"@ai-sdk/provider\";\nimport {\n  UnsupportedAISDKModelProviderError,\n  UnsupportedModelError,\n  UnsupportedModelProviderError,\n} from \"../types/public/sdkErrors.js\";\nimport { LogLine } from \"../types/public/logs.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelProvider,\n} from \"../types/public/model.js\";\nimport { AISdkClient } from \"./aisdk.js\";\nimport { AnthropicClient } from \"./AnthropicClient.js\";\nimport { CerebrasClient } from \"./CerebrasClient.js\";\nimport { GoogleClient } from \"./GoogleClient.js\";\nimport { GroqClient } from \"./GroqClient.js\";\nimport { LLMClient } from \"./LLMClient.js\";\nimport { OpenAIClient } from \"./OpenAIClient.js\";\nimport { openai, createOpenAI } from \"@ai-sdk/openai\";\nimport { bedrock, createAmazonBedrock } from \"@ai-sdk/amazon-bedrock\";\nimport { vertex, createVertex } from \"@ai-sdk/google-vertex\";\nimport { anthropic, createAnthropic } from \"@ai-sdk/anthropic\";\nimport { google, createGoogleGenerativeAI } from \"@ai-sdk/google\";\nimport { xai, createXai } from \"@ai-sdk/xai\";\nimport { azure, createAzure } from \"@ai-sdk/azure\";\nimport { groq, createGroq } from \"@ai-sdk/groq\";\nimport { cerebras, createCerebras } from \"@ai-sdk/cerebras\";\nimport { togetherai, createTogetherAI } from \"@ai-sdk/togetherai\";\nimport { mistral, createMistral } from \"@ai-sdk/mistral\";\nimport { deepseek, createDeepSeek } from \"@ai-sdk/deepseek\";\nimport { perplexity, createPerplexity } from \"@ai-sdk/perplexity\";\nimport { ollama, createOllama } from \"ollama-ai-provider-v2\";\nimport { gateway, createGateway, wrapLanguageModel } from \"ai\";\nimport { AISDKProvider, AISDKCustomProvider } from \"../types/public/model.js\";\n\nconst AISDKProviders: Record<string, AISDKProvider> = {\n  openai,\n  bedrock,\n  anthropic,\n  google,\n  xai,\n  azure,\n  groq,\n  cerebras,\n  togetherai,\n  mistral,\n  deepseek,\n  perplexity,\n  ollama,\n  vertex,\n  gateway,\n};\nconst AISDKProvidersWithAPIKey: Record<string, AISDKCustomProvider> = {\n  openai: createOpenAI,\n  bedrock: createAmazonBedrock,\n  anthropic: createAnthropic,\n  google: createGoogleGenerativeAI,\n  vertex: createVertex,\n  xai: createXai,\n  azure: createAzure,\n  groq: createGroq,\n  cerebras: createCerebras,\n  togetherai: createTogetherAI,\n  mistral: createMistral,\n  deepseek: createDeepSeek,\n  perplexity: createPerplexity,\n  ollama: createOllama,\n  gateway: createGateway,\n};\n\ntype AISDKProviderClientOptions = ClientOptions & Record<string, unknown>;\n\nexport function toAISDKClientOptions(\n  subProvider: string,\n  clientOptions?: ClientOptions,\n): AISDKProviderClientOptions | undefined {\n  if (!clientOptions || subProvider !== \"vertex\") {\n    return clientOptions as AISDKProviderClientOptions | undefined;\n  }\n\n  const { auth, providerOptions, ...rest } = clientOptions;\n  const vertexOptions = providerOptions?.vertex;\n\n  return {\n    ...rest,\n    ...(vertexOptions ?? {}),\n    ...(auth?.type === \"googleServiceAccount\"\n      ? {\n          googleAuthOptions: {\n            credentials: auth.credentials,\n            ...(auth.scopes ? { scopes: auth.scopes } : {}),\n            ...(auth.projectId ? { projectId: auth.projectId } : {}),\n            ...(auth.universeDomain\n              ? { universeDomain: auth.universeDomain }\n              : {}),\n          },\n        }\n      : {}),\n  };\n}\n\nconst modelToProviderMap: { [key in AvailableModel]: ModelProvider } = {\n  \"gpt-4.1\": \"openai\",\n  \"gpt-4.1-mini\": \"openai\",\n  \"gpt-4.1-nano\": \"openai\",\n  \"o4-mini\": \"openai\",\n  //prettier-ignore\n  \"o3\": \"openai\",\n  \"o3-mini\": \"openai\",\n  //prettier-ignore\n  \"o1\": \"openai\",\n  \"o1-mini\": \"openai\",\n  \"gpt-4o\": \"openai\",\n  \"gpt-4o-mini\": \"openai\",\n  \"gpt-4o-2024-08-06\": \"openai\",\n  \"gpt-4.5-preview\": \"openai\",\n  \"o1-preview\": \"openai\",\n  \"cerebras-llama-3.3-70b\": \"cerebras\",\n  \"cerebras-llama-3.1-8b\": \"cerebras\",\n  \"groq-llama-3.3-70b-versatile\": \"groq\",\n  \"groq-llama-3.3-70b-specdec\": \"groq\",\n  \"moonshotai/kimi-k2-instruct\": \"groq\",\n  \"gemini-1.5-flash\": \"google\",\n  \"gemini-1.5-pro\": \"google\",\n  \"gemini-1.5-flash-8b\": \"google\",\n  \"gemini-2.0-flash-lite\": \"google\",\n  \"gemini-2.0-flash\": \"google\",\n  \"gemini-2.5-flash-preview-04-17\": \"google\",\n  \"gemini-2.5-pro-preview-03-25\": \"google\",\n};\n\nexport function getAISDKLanguageModel(\n  subProvider: string,\n  subModelName: string,\n  clientOptions?: ClientOptions,\n  middleware?: LanguageModelV2Middleware,\n) {\n  const aiSdkClientOptions = toAISDKClientOptions(subProvider, clientOptions);\n  const hasValidOptions =\n    aiSdkClientOptions &&\n    Object.values(aiSdkClientOptions).some(\n      (v) => v !== undefined && v !== null,\n    );\n\n  let model;\n  if (hasValidOptions) {\n    const creator = AISDKProvidersWithAPIKey[subProvider];\n    if (!creator) {\n      throw new UnsupportedAISDKModelProviderError(\n        subProvider,\n        Object.keys(AISDKProvidersWithAPIKey),\n      );\n    }\n    const provider = creator(aiSdkClientOptions as ClientOptions);\n    model = provider(subModelName);\n  } else {\n    const provider = AISDKProviders[subProvider];\n    if (!provider) {\n      throw new UnsupportedAISDKModelProviderError(\n        subProvider,\n        Object.keys(AISDKProviders),\n      );\n    }\n    model = provider(subModelName);\n  }\n\n  if (middleware) {\n    return wrapLanguageModel({ model, middleware });\n  }\n  return model;\n}\n\nexport class LLMProvider {\n  private logger: (message: LogLine) => void;\n  private middleware?: LanguageModelV2Middleware;\n\n  constructor(\n    logger: (message: LogLine) => void,\n    middleware?: LanguageModelV2Middleware,\n  ) {\n    this.logger = logger;\n    this.middleware = middleware;\n  }\n\n  getClient(\n    modelName: AvailableModel,\n    clientOptions?: ClientOptions,\n    options?: {\n      experimental?: boolean;\n      disableAPI?: boolean;\n      middleware?: LanguageModelV2Middleware;\n    },\n  ): LLMClient {\n    if (modelName.includes(\"/\")) {\n      const firstSlashIndex = modelName.indexOf(\"/\");\n      const subProvider = modelName.substring(0, firstSlashIndex);\n      const subModelName = modelName.substring(firstSlashIndex + 1);\n\n      const effectiveMiddleware = options?.middleware ?? this.middleware;\n      const languageModel = getAISDKLanguageModel(\n        subProvider,\n        subModelName,\n        clientOptions,\n        effectiveMiddleware,\n      );\n\n      return new AISdkClient({\n        model: languageModel,\n        logger: this.logger,\n        clientOptions,\n      });\n    }\n\n    // Model name doesn't include \"/\" - this format is deprecated\n    const provider = modelToProviderMap[modelName];\n    if (!provider) {\n      throw new UnsupportedModelError(Object.keys(modelToProviderMap));\n    }\n\n    this.logger({\n      category: \"llm\",\n      message: `Deprecation warning: Model format \"${modelName}\" is deprecated. Please use the provider/model format (e.g., \"openai/gpt-5\" or \"anthropic/claude-sonnet-4\").`,\n      level: 0,\n    });\n\n    const availableModel = modelName as AvailableModel;\n    switch (provider) {\n      case \"openai\":\n        return new OpenAIClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"anthropic\":\n        return new AnthropicClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"cerebras\":\n        return new CerebrasClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"groq\":\n        return new GroqClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"google\":\n        return new GoogleClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      default:\n        // This default case handles unknown providers that exist in modelToProviderMap\n        // but aren't implemented in the switch. This is an internal consistency issue.\n        throw new UnsupportedModelProviderError([\n          ...new Set(Object.values(modelToProviderMap)),\n        ]);\n    }\n  }\n\n  static getModelProvider(modelName: AvailableModel): ModelProvider {\n    if (modelName.includes(\"/\")) {\n      const firstSlashIndex = modelName.indexOf(\"/\");\n      const subProvider = modelName.substring(0, firstSlashIndex);\n      if (AISDKProviders[subProvider]) {\n        return \"aisdk\";\n      }\n    }\n    const provider = modelToProviderMap[modelName];\n    return provider;\n  }\n}\n"]}
+{"version":3,"file":"LLMProvider.js","sourceRoot":"","sources":["../../../../../lib/v3/llm/LLMProvider.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LanguageModelV2Middleware } from \"@ai-sdk/provider\";\nimport {\n  UnsupportedAISDKModelProviderError,\n  UnsupportedModelError,\n  UnsupportedModelProviderError,\n} from \"../types/public/sdkErrors.js\";\nimport { LogLine } from \"../types/public/logs.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelProvider,\n} from \"../types/public/model.js\";\nimport { AISdkClient } from \"./aisdk.js\";\nimport { AnthropicClient } from \"./AnthropicClient.js\";\nimport { CerebrasClient } from \"./CerebrasClient.js\";\nimport { GoogleClient } from \"./GoogleClient.js\";\nimport { GroqClient } from \"./GroqClient.js\";\nimport { LLMClient } from \"./LLMClient.js\";\nimport { OpenAIClient } from \"./OpenAIClient.js\";\nimport { openai, createOpenAI } from \"@ai-sdk/openai\";\nimport { bedrock, createAmazonBedrock } from \"@ai-sdk/amazon-bedrock\";\nimport { vertex, createVertex } from \"@ai-sdk/google-vertex\";\nimport { anthropic, createAnthropic } from \"@ai-sdk/anthropic\";\nimport { google, createGoogleGenerativeAI } from \"@ai-sdk/google\";\nimport { xai, createXai } from \"@ai-sdk/xai\";\nimport { azure, createAzure } from \"@ai-sdk/azure\";\nimport { groq, createGroq } from \"@ai-sdk/groq\";\nimport { cerebras, createCerebras } from \"@ai-sdk/cerebras\";\nimport { togetherai, createTogetherAI } from \"@ai-sdk/togetherai\";\nimport { mistral, createMistral } from \"@ai-sdk/mistral\";\nimport { deepseek, createDeepSeek } from \"@ai-sdk/deepseek\";\nimport { perplexity, createPerplexity } from \"@ai-sdk/perplexity\";\nimport { ollama, createOllama } from \"ollama-ai-provider-v2\";\nimport { gateway, createGateway, wrapLanguageModel } from \"ai\";\nimport { AISDKProvider, AISDKCustomProvider } from \"../types/public/model.js\";\n\nconst AISDKProviders: Record<string, AISDKProvider> = {\n  openai,\n  bedrock,\n  anthropic,\n  google,\n  xai,\n  azure,\n  groq,\n  cerebras,\n  togetherai,\n  mistral,\n  deepseek,\n  perplexity,\n  ollama,\n  vertex,\n  gateway,\n};\nconst AISDKProvidersWithAPIKey: Record<string, AISDKCustomProvider> = {\n  openai: createOpenAI,\n  bedrock: createAmazonBedrock,\n  anthropic: createAnthropic,\n  google: createGoogleGenerativeAI,\n  vertex: createVertex,\n  xai: createXai,\n  azure: createAzure,\n  groq: createGroq,\n  cerebras: createCerebras,\n  togetherai: createTogetherAI,\n  mistral: createMistral,\n  deepseek: createDeepSeek,\n  perplexity: createPerplexity,\n  ollama: createOllama,\n  gateway: createGateway,\n};\n\ntype AISDKProviderClientOptions = ClientOptions & Record<string, unknown>;\n\nexport function toAISDKClientOptions(\n  subProvider: string,\n  clientOptions?: ClientOptions,\n): AISDKProviderClientOptions | undefined {\n  if (!clientOptions) {\n    return clientOptions as AISDKProviderClientOptions | undefined;\n  }\n\n  const { auth, providerOptions, apiKey, ...rest } = clientOptions;\n  const apiKeyOption = !auth && apiKey ? { apiKey } : {};\n\n  if (subProvider === \"azure\") {\n    const azureOptions = providerOptions?.azure;\n\n    return {\n      ...rest,\n      ...apiKeyOption,\n      ...(azureOptions ?? {}),\n      ...(auth?.type === \"azureEntraId\"\n        ? { tokenProvider: async () => auth.token }\n        : {}),\n    };\n  }\n\n  if (subProvider !== \"vertex\") {\n    return clientOptions as AISDKProviderClientOptions | undefined;\n  }\n\n  const vertexOptions = providerOptions?.vertex;\n\n  return {\n    ...rest,\n    ...apiKeyOption,\n    ...(vertexOptions ?? {}),\n    ...(auth?.type === \"googleServiceAccount\"\n      ? {\n          googleAuthOptions: {\n            credentials: auth.credentials,\n            ...(auth.scopes ? { scopes: auth.scopes } : {}),\n            ...(auth.projectId ? { projectId: auth.projectId } : {}),\n            ...(auth.universeDomain\n              ? { universeDomain: auth.universeDomain }\n              : {}),\n          },\n        }\n      : {}),\n  };\n}\n\nconst modelToProviderMap: { [key in AvailableModel]: ModelProvider } = {\n  \"gpt-4.1\": \"openai\",\n  \"gpt-4.1-mini\": \"openai\",\n  \"gpt-4.1-nano\": \"openai\",\n  \"o4-mini\": \"openai\",\n  //prettier-ignore\n  \"o3\": \"openai\",\n  \"o3-mini\": \"openai\",\n  //prettier-ignore\n  \"o1\": \"openai\",\n  \"o1-mini\": \"openai\",\n  \"gpt-4o\": \"openai\",\n  \"gpt-4o-mini\": \"openai\",\n  \"gpt-4o-2024-08-06\": \"openai\",\n  \"gpt-4.5-preview\": \"openai\",\n  \"o1-preview\": \"openai\",\n  \"cerebras-llama-3.3-70b\": \"cerebras\",\n  \"cerebras-llama-3.1-8b\": \"cerebras\",\n  \"groq-llama-3.3-70b-versatile\": \"groq\",\n  \"groq-llama-3.3-70b-specdec\": \"groq\",\n  \"moonshotai/kimi-k2-instruct\": \"groq\",\n  \"gemini-1.5-flash\": \"google\",\n  \"gemini-1.5-pro\": \"google\",\n  \"gemini-1.5-flash-8b\": \"google\",\n  \"gemini-2.0-flash-lite\": \"google\",\n  \"gemini-2.0-flash\": \"google\",\n  \"gemini-2.5-flash-preview-04-17\": \"google\",\n  \"gemini-2.5-pro-preview-03-25\": \"google\",\n};\n\nexport function getAISDKLanguageModel(\n  subProvider: string,\n  subModelName: string,\n  clientOptions?: ClientOptions,\n  middleware?: LanguageModelV2Middleware,\n) {\n  const aiSdkClientOptions = toAISDKClientOptions(subProvider, clientOptions);\n  const hasValidOptions =\n    aiSdkClientOptions &&\n    Object.values(aiSdkClientOptions).some(\n      (v) => v !== undefined && v !== null,\n    );\n\n  let model;\n  if (hasValidOptions) {\n    const creator = AISDKProvidersWithAPIKey[subProvider];\n    if (!creator) {\n      throw new UnsupportedAISDKModelProviderError(\n        subProvider,\n        Object.keys(AISDKProvidersWithAPIKey),\n      );\n    }\n    const provider = creator(aiSdkClientOptions as ClientOptions);\n    model = provider(subModelName);\n  } else {\n    const provider = AISDKProviders[subProvider];\n    if (!provider) {\n      throw new UnsupportedAISDKModelProviderError(\n        subProvider,\n        Object.keys(AISDKProviders),\n      );\n    }\n    model = provider(subModelName);\n  }\n\n  if (middleware) {\n    return wrapLanguageModel({ model, middleware });\n  }\n  return model;\n}\n\nexport class LLMProvider {\n  private logger: (message: LogLine) => void;\n  private middleware?: LanguageModelV2Middleware;\n\n  constructor(\n    logger: (message: LogLine) => void,\n    middleware?: LanguageModelV2Middleware,\n  ) {\n    this.logger = logger;\n    this.middleware = middleware;\n  }\n\n  getClient(\n    modelName: AvailableModel,\n    clientOptions?: ClientOptions,\n    options?: {\n      experimental?: boolean;\n      disableAPI?: boolean;\n      middleware?: LanguageModelV2Middleware;\n    },\n  ): LLMClient {\n    if (modelName.includes(\"/\")) {\n      const firstSlashIndex = modelName.indexOf(\"/\");\n      const subProvider = modelName.substring(0, firstSlashIndex);\n      const subModelName = modelName.substring(firstSlashIndex + 1);\n\n      const effectiveMiddleware = options?.middleware ?? this.middleware;\n      const languageModel = getAISDKLanguageModel(\n        subProvider,\n        subModelName,\n        clientOptions,\n        effectiveMiddleware,\n      );\n\n      return new AISdkClient({\n        model: languageModel,\n        logger: this.logger,\n        clientOptions,\n      });\n    }\n\n    // Model name doesn't include \"/\" - this format is deprecated\n    const provider = modelToProviderMap[modelName];\n    if (!provider) {\n      throw new UnsupportedModelError(Object.keys(modelToProviderMap));\n    }\n\n    this.logger({\n      category: \"llm\",\n      message: `Deprecation warning: Model format \"${modelName}\" is deprecated. Please use the provider/model format (e.g., \"openai/gpt-5\" or \"anthropic/claude-sonnet-4\").`,\n      level: 0,\n    });\n\n    const availableModel = modelName as AvailableModel;\n    switch (provider) {\n      case \"openai\":\n        return new OpenAIClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"anthropic\":\n        return new AnthropicClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"cerebras\":\n        return new CerebrasClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"groq\":\n        return new GroqClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      case \"google\":\n        return new GoogleClient({\n          logger: this.logger,\n          modelName: availableModel,\n          clientOptions,\n        });\n      default:\n        // This default case handles unknown providers that exist in modelToProviderMap\n        // but aren't implemented in the switch. This is an internal consistency issue.\n        throw new UnsupportedModelProviderError([\n          ...new Set(Object.values(modelToProviderMap)),\n        ]);\n    }\n  }\n\n  static getModelProvider(modelName: AvailableModel): ModelProvider {\n    if (modelName.includes(\"/\")) {\n      const firstSlashIndex = modelName.indexOf(\"/\");\n      const subProvider = modelName.substring(0, firstSlashIndex);\n      if (AISDKProviders[subProvider]) {\n        return \"aisdk\";\n      }\n    }\n    const provider = modelToProviderMap[modelName];\n    return provider;\n  }\n}\n"]}

package/dist/cjs/lib/v3/types/public/agent.d.ts

@@ -401,8 +401,8 @@ export interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {
      */
     callbacks?: AgentStreamCallbacks;
 }
-export type AgentType = "openai" | "anthropic" | "google" | "microsoft" | "bedrock" | "vertex";
-export declare const AVAILABLE_CUA_MODELS: readonly ["openai/gpt-5.4", "openai/gpt-5.4-mini", "openai/gpt-5.5", "openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
+export type AgentType = "openai" | "anthropic" | "google" | "microsoft" | "bedrock" | "vertex" | "azure";
+export declare const AVAILABLE_CUA_MODELS: readonly ["openai/gpt-5.4", "openai/gpt-5.4-mini", "openai/gpt-5.5", "openai/computer-use-preview", "openai/computer-use-preview-2025-03-11", "anthropic/claude-opus-4-5-20251101", "anthropic/claude-opus-4-6", "anthropic/claude-opus-4-8", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-20250514", "anthropic/claude-sonnet-4-5-20250929", "google/gemini-2.5-computer-use-preview-10-2025", "google/gemini-3-flash-preview", "google/gemini-3-pro-preview", "microsoft/fara-7b"];
 export type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];
 export interface AgentExecutionOptions<TOptions extends AgentExecuteOptions = AgentExecuteOptions> {
     options: TOptions;

package/dist/cjs/lib/v3/types/public/agent.js

@@ -9,6 +9,7 @@ exports.AVAILABLE_CUA_MODELS = [
     "openai/computer-use-preview-2025-03-11",
     "anthropic/claude-opus-4-5-20251101",
     "anthropic/claude-opus-4-6",
+    "anthropic/claude-opus-4-8",
     "anthropic/claude-sonnet-4-6",
     "anthropic/claude-haiku-4-5",
     "anthropic/claude-haiku-4-5-20251001",

package/dist/cjs/lib/v3/types/public/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/agent.ts"],"names":[],"mappings":";;;AAwca,QAAA,oBAAoB,GAAG;IAClC,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,6BAA6B;IAC7B,wCAAwC;IACxC,oCAAoC;IACpC,2BAA2B;IAC3B,6BAA6B;IAC7B,4BAA4B;IAC5B,qCAAqC;IACrC,oCAAoC;IACpC,sCAAsC;IACtC,gDAAgD;IAChD,+BAA+B;IAC/B,6BAA6B;IAC7B,mBAAmB;CACX,CAAC","sourcesContent":["import type { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport {\n  ToolSet,\n  ModelMessage,\n  wrapLanguageModel,\n  StreamTextResult,\n  StepResult,\n  PrepareStepFunction,\n  GenerateTextOnStepFinishCallback,\n  StreamTextOnStepFinishCallback,\n  StreamTextOnErrorCallback,\n  StreamTextOnChunkCallback,\n  StreamTextOnFinishCallback,\n} from \"ai\";\nimport { LogLine } from \"./logs.js\";\nimport { ClientOptions } from \"./model.js\";\nimport { StagehandZodObject } from \"../../zodCompat.js\";\nimport type { AgentEvidenceCallback } from \"./agentEvidenceEvents.js\";\n\n// Re-export ModelMessage for consumers who want to use it for conversation continuation\nexport type { ModelMessage } from \"ai\";\n\n// Re-export Tool type for consumers who want to define custom tools\nexport type { Tool } from \"ai\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\nimport { Page as PatchrightPage } from \"patchright-core\";\nimport { Page } from \"../../understudy/page.js\";\n\n// =============================================================================\n// Variable Types\n// =============================================================================\n\n/**\n * A variable value can be a simple primitive or a rich object with an optional description.\n * This unified type is shared across `act`, `agent.execute`, and other methods.\n *\n * @example Simple (backward-compatible):\n * ```typescript\n * variables: { username: \"john@example.com\" }\n * ```\n *\n * @example Rich with description (useful for agents):\n * ```typescript\n * variables: {\n *   username: { value: \"john@example.com\", description: \"The login email\" }\n * }\n * ```\n */\nexport type VariableValue =\n  | string\n  | number\n  | boolean\n  | { value: string | number | boolean; description?: string };\n\n/**\n * A collection of named variables for use in act, agent, and other methods.\n */\nexport type Variables = Record<string, VariableValue>;\n\nexport interface AgentContext {\n  options: AgentExecuteOptionsBase;\n  maxSteps: number;\n  systemPrompt: string;\n  allTools: ToolSet;\n  messages: ModelMessage[];\n  wrappedModel: ReturnType<typeof wrapLanguageModel>;\n  initialPageUrl: string;\n}\n\nexport interface AgentState {\n  collectedReasoning: string[];\n  actions: AgentAction[];\n  finalMessage: string;\n  completed: boolean;\n  currentPageUrl: string;\n}\n\nexport interface AgentAction {\n  type: string;\n  reasoning?: string;\n  taskCompleted?: boolean;\n  action?: string;\n  // Tool-specific fields\n  timeMs?: number; // wait tool\n  pageText?: string; // ariaTree tool\n  pageUrl?: string; // ariaTree tool\n  instruction?: string; // various tools\n  [key: string]: unknown;\n}\n\nexport interface AgentResult {\n  success: boolean;\n  message: string;\n  actions: AgentAction[];\n  completed: boolean;\n  metadata?: Record<string, unknown>;\n  usage?: {\n    input_tokens: number;\n    output_tokens: number;\n    reasoning_tokens?: number;\n    cached_input_tokens?: number;\n    inference_time_ms: number;\n  };\n  /**\n   * The conversation messages from this execution.\n   * Pass these to a subsequent execute() call via the `messages` option to continue the conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * Custom output data extracted based on the `output` schema provided in execute options.\n   * Only populated if an `output` schema was provided.\n   * @experimental\n   */\n  output?: Record<string, unknown>;\n}\n\nexport type AgentStreamResult = StreamTextResult<ToolSet, never> & {\n  result: Promise<AgentResult>;\n};\n\n/**\n * Base callbacks shared between execute (non-streaming) and streaming modes.\n */\nexport interface AgentCallbacks {\n  /**\n   * Optional function called before each step to modify settings.\n   * You can change the model, tool choices, active tools, system prompt,\n   * and input messages for each step.\n   */\n  prepareStep?: PrepareStepFunction<ToolSet>;\n  /**\n   * Callback called when each step (LLM call) is finished.\n   * This is called for intermediate steps as well as the final step.\n   */\n  onStepFinish?:\n    | GenerateTextOnStepFinishCallback<ToolSet>\n    | StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when Stagehand captures agent-run evidence such as\n   * screenshots, completed tool/action steps, or post-action observations.\n   */\n  onEvidence?: AgentEvidenceCallback;\n}\n\n/**\n * Error message type for streaming-only callbacks used in non-streaming mode.\n * This provides a clear error message when users try to use streaming callbacks without stream: true.\n */\ntype StreamingCallbackNotAvailable =\n  \"This callback requires 'stream: true' in AgentConfig. Set stream: true to use streaming callbacks like onChunk, onFinish, onError, and onAbort.\";\n\n/**\n * Error message for safety confirmation callback misuse.\n * Safety confirmations are only available for non-streaming CUA agent executions.\n */\ntype SafetyConfirmationCallbackNotAvailable =\n  \"Safety confirmation callbacks are only available via non-streaming AgentExecuteOptions.callbacks when using mode: 'cua'.\";\n\n/**\n * Callbacks specific to the non-streaming execute method.\n */\nexport interface AgentExecuteCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished.\n   */\n  onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback for handling safety confirmation requests from CUA providers.\n   * Only available when running an agent configured with mode: \"cua\".\n   */\n  onSafetyConfirmation?: SafetyConfirmationHandler;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onChunk:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onChunk: async (chunk) => console.log(chunk) }\n   * });\n   * ```\n   */\n  onChunk?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onFinish:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onFinish: (event) => console.log(\"Done!\", event) }\n   * });\n   * ```\n   */\n  onFinish?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onError:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onError: ({ error }) => console.error(error) }\n   * });\n   * ```\n   */\n  onError?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onAbort:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onAbort: (event) => console.log(\"Aborted\", event.steps) }\n   * });\n   * ```\n   */\n  onAbort?: StreamingCallbackNotAvailable;\n}\n\n/**\n * Callbacks specific to the streaming mode.\n */\nexport interface AgentStreamCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished during streaming.\n   */\n  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when an error occurs during streaming.\n   * Use this to log errors or handle error states.\n   */\n  onError?: StreamTextOnErrorCallback;\n  /**\n   * Callback called for each chunk of the stream.\n   * Stream processing will pause until the callback promise resolves.\n   */\n  onChunk?: StreamTextOnChunkCallback<ToolSet>;\n  /**\n   * Callback called when the stream finishes.\n   */\n  onFinish?: StreamTextOnFinishCallback<ToolSet>;\n  /**\n   * Callback called when the stream is aborted.\n   */\n  onAbort?: (event: {\n    steps: Array<StepResult<ToolSet>>;\n  }) => PromiseLike<void> | void;\n  /**\n   * NOT AVAILABLE in streaming mode.\n   * Safety confirmations currently require non-streaming execute() on CUA agents.\n   */\n  onSafetyConfirmation?: SafetyConfirmationCallbackNotAvailable;\n}\n\n/**\n * Base options for agent execution (without callbacks).\n */\nexport interface AgentExecuteOptionsBase {\n  instruction: string;\n  maxSteps?: number;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  highlightCursor?: boolean;\n  /**\n   * Previous conversation messages to continue from.\n   * Pass the `messages` from a previous AgentResult to continue that conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * An AbortSignal that can be used to cancel the agent execution.\n   * When aborted, the agent will stop and return a partial result.\n   * @experimental\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * setTimeout(() => controller.abort(), 30000); // 30 second timeout\n   *\n   * const result = await agent.execute({\n   *   instruction: \"...\",\n   *   signal: controller.signal\n   * });\n   * ```\n   */\n  signal?: AbortSignal;\n  /**\n   * Tools to exclude from this execution.\n   * Pass an array of tool names to prevent the agent from using those tools.\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * **Available tools by mode:**\n   *\n   * **DOM mode (default):**\n   * - `act` - Perform semantic actions (click, type, etc.)\n   * - `fillForm` - Fill form fields using DOM selectors\n   * - `ariaTree` - Get accessibility tree of the page\n   * - `extract` - Extract structured data from page\n   * - `goto` - Navigate to a URL\n   * - `scroll` - Scroll using semantic directions (up/down/left/right)\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back in history\n   * - `screenshot` - Take a screenshot\n   * - `think` - Agent reasoning/planning step\n   * - `wait` - Wait for time or condition\n   * - `done` - Mark task as complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * **Hybrid mode:**\n   * - `click` - Click at specific coordinates\n   * - `type` - Type text at coordinates\n   * - `dragAndDrop` - Drag from one point to another\n   * - `clickAndHold` - Click and hold at coordinates\n   * - `fillFormVision` - Fill forms using vision/coordinates\n   * - `act` - Perform semantic actions\n   * - `ariaTree` - Get accessibility tree\n   * - `extract` - Extract data from page\n   * - `goto` - Navigate to URL\n   * - `scroll` - Scroll using coordinates\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back\n   * - `screenshot` - Take screenshot\n   * - `think` - Agent reasoning step\n   * - `wait` - Wait for time/condition\n   * - `done` - Mark task complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * // Exclude screenshot and extract tools\n   * const result = await agent.execute({\n   *   instruction: \"Click the submit button\",\n   *   excludeTools: [\"screenshot\", \"extract\"]\n   * });\n   * ```\n   */\n  excludeTools?: string[];\n  /**\n   * A Zod schema defining custom output data to return when the task completes.\n   * The agent will populate this data in the final done tool call.\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the cheapest flight from NYC to LA\",\n   *   output: z.object({\n   *     price: z.string().describe(\"The price of the flight\"),\n   *     airline: z.string().describe(\"The airline name\"),\n   *     departureTime: z.string().describe(\"Departure time\"),\n   *   }),\n   * });\n   *\n   * console.log(result.output); // { price: \"$199\", airline: \"Delta\", departureTime: \"8:00 AM\" }\n   * ```\n   */\n  output?: StagehandZodObject;\n  /**\n   * Variables that the agent can use when filling forms or typing text.\n   * The agent will see variable names and descriptions in the system prompt,\n   * and can use them via `%variableName%` syntax in act/type/fillForm tool calls.\n   *\n   * Accepts both simple values and rich objects with descriptions (same type as `act`).\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * @example\n   * ```typescript\n   * // Simple values\n   * variables: { username: \"john@example.com\", password: \"secret123\" }\n   *\n   * // Rich values with descriptions (helps the agent understand context)\n   * variables: {\n   *   username: { value: \"john@example.com\", description: \"The login email\" },\n   *   password: { value: \"secret123\", description: \"The login password\" },\n   * }\n   * ```\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for each agent tool call.\n   * If a tool call exceeds this duration, it will be aborted and\n   * reported back to the LLM as a timeout error so it can retry or adjust.\n   * For tools that call v3 methods (act, extract, fillForm, ariaTree), the\n   * timeout is also forwarded to the underlying v3 call for true cancellation.\n   * @default 45000 (45 seconds)\n   */\n  toolTimeout?: number;\n  /**\n   * Enable the web search tool powered by Browserbase Search API.\n   * Requires a valid Browserbase API key (BROWSERBASE_API_KEY).\n   * When set to true, the agent gains access to a `search` tool for web searches.\n   *\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the latest news about AI\",\n   *   useSearch: true,\n   * });\n   * ```\n   */\n  useSearch?: boolean;\n}\n\n/**\n * Options for non-streaming agent execution.\n * Only accepts AgentExecuteCallbacks (no streaming-specific callbacks like onChunk, onFinish).\n */\nexport interface AgentExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for non-streaming agent execution.\n   * For streaming callbacks (onChunk, onFinish, onError, onAbort), use stream: true in AgentConfig.\n   */\n  callbacks?: AgentExecuteCallbacks;\n}\n\n/**\n * Options for streaming agent execution.\n * Accepts AgentStreamCallbacks including onChunk, onFinish, onError, and onAbort.\n */\nexport interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for streaming agent execution.\n   * Includes streaming-specific callbacks: onChunk, onFinish, onError, onAbort.\n   */\n  callbacks?: AgentStreamCallbacks;\n}\nexport type AgentType =\n  | \"openai\"\n  | \"anthropic\"\n  | \"google\"\n  | \"microsoft\"\n  | \"bedrock\"\n  | \"vertex\";\n\nexport const AVAILABLE_CUA_MODELS = [\n  \"openai/gpt-5.4\",\n  \"openai/gpt-5.4-mini\",\n  \"openai/gpt-5.5\",\n  \"openai/computer-use-preview\",\n  \"openai/computer-use-preview-2025-03-11\",\n  \"anthropic/claude-opus-4-5-20251101\",\n  \"anthropic/claude-opus-4-6\",\n  \"anthropic/claude-sonnet-4-6\",\n  \"anthropic/claude-haiku-4-5\",\n  \"anthropic/claude-haiku-4-5-20251001\",\n  \"anthropic/claude-sonnet-4-20250514\",\n  \"anthropic/claude-sonnet-4-5-20250929\",\n  \"google/gemini-2.5-computer-use-preview-10-2025\",\n  \"google/gemini-3-flash-preview\",\n  \"google/gemini-3-pro-preview\",\n  \"microsoft/fara-7b\",\n] as const;\nexport type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];\n\nexport interface AgentExecutionOptions<\n  TOptions extends AgentExecuteOptions = AgentExecuteOptions,\n> {\n  options: TOptions;\n  logger: (message: LogLine) => void;\n  retries?: number;\n}\n\nexport interface AgentHandlerOptions {\n  modelName: string;\n  clientOptions?: ClientOptions;\n  userProvidedInstructions?: string;\n  experimental?: boolean;\n}\n\nexport interface ActionExecutionResult {\n  success: boolean;\n  error?: string;\n  data?: unknown;\n}\n\n/**\n * Represents a safety check that requires user confirmation before proceeding.\n * These are issued by CUA providers (OpenAI, Google) when the agent attempts\n * potentially risky actions.\n */\nexport interface SafetyCheck {\n  /** Unique identifier for this safety check */\n  id: string;\n  /** Code identifying the type of safety concern */\n  code: string;\n  /** Human-readable description of the safety concern */\n  message: string;\n}\n\n/**\n * Response from the user for a safety confirmation request.\n */\nexport interface SafetyConfirmationResponse {\n  /** Whether the user acknowledged/approved the safety checks */\n  acknowledged: boolean;\n}\n\n/**\n * Callback for handling safety confirmation requests.\n * Called when the CUA provider issues safety checks that require user confirmation.\n * The callback should return a promise that resolves when the user has made a decision.\n *\n * @param safetyChecks - Array of safety checks requiring confirmation\n * @returns Promise resolving to the user's response\n *\n * @example\n * ```typescript\n * const agent = stagehand.agent({\n *   mode: \"cua\",\n * });\n * await agent.execute({\n *   instruction: \"...\",\n *   callbacks: {\n *     onSafetyConfirmation: async (checks) => {\n *       console.log(\"Safety checks:\", checks);\n *       const userApproved = await showConfirmationDialog(checks);\n *       return { acknowledged: userApproved };\n *     },\n *   },\n * });\n * ```\n */\nexport type SafetyConfirmationHandler = (\n  safetyChecks: SafetyCheck[],\n) => Promise<SafetyConfirmationResponse>;\n\n// Anthropic types:\n\nexport interface ToolUseItem extends ResponseItem {\n  type: \"tool_use\";\n  id: string; // This is the correct property name from Anthropic's API\n  name: string; // Name of the tool being used\n  input: Record<string, unknown>;\n}\n\nexport interface AnthropicMessage {\n  role: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\nexport interface AnthropicContentBlock {\n  type: string;\n  [key: string]: unknown;\n}\n\nexport interface AnthropicTextBlock extends AnthropicContentBlock {\n  type: \"text\";\n  text: string;\n}\n\nexport interface AnthropicToolResult {\n  type: \"tool_result\";\n  tool_use_id: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\n// OpenAI types:\n\nexport interface ResponseItem {\n  type: string;\n  id: string;\n  [key: string]: unknown;\n}\n\nexport interface ComputerCallItem extends ResponseItem {\n  type: \"computer_call\";\n  call_id: string;\n  action?: {\n    type: string;\n    [key: string]: unknown;\n  };\n  actions?: Array<{\n    type: string;\n    [key: string]: unknown;\n  }>;\n  pending_safety_checks?: Array<{\n    id: string;\n    code: string;\n    message: string;\n  }>;\n}\n\nexport interface FunctionCallItem extends ResponseItem {\n  type: \"function_call\";\n  call_id: string;\n  name: string;\n  arguments: string;\n}\n\nexport type ResponseInputItem =\n  | { role: string; content: string }\n  | {\n      type: \"computer_call_output\";\n      call_id: string;\n      output:\n        | {\n            type: \"input_image\" | \"computer_screenshot\";\n            image_url: string;\n            detail?: \"original\" | \"high\" | \"low\";\n            current_url?: string;\n            error?: string;\n            [key: string]: unknown;\n          }\n        | string;\n      acknowledged_safety_checks?: Array<{\n        id: string;\n        code: string;\n        message: string;\n      }>;\n    }\n  | {\n      type: \"function_call_output\";\n      call_id: string;\n      output: string;\n    };\n\nexport interface AgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\nexport type AgentProviderType = AgentType;\n\nexport type AgentModelConfig<TModelName extends string = string> = {\n  modelName: TModelName;\n} & Record<string, unknown>;\n\n/**\n * Agent tool mode determines which set of tools are available to the agent.\n * - 'dom': Uses DOM-based tools (act, fillForm) - better for structured page interactions\n * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - better for visual/screenshot-based interactions\n * - 'cua': Uses Computer Use Agent (CUA) providers like Anthropic Claude or Google Gemini for screenshot-based automation\n */\nexport type AgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\nexport type AgentConfig = {\n  /**\n   * Custom system prompt to provide to the agent. Overrides the default system prompt.\n   */\n  systemPrompt?: string;\n  /**\n   * MCP integrations - Array of Client objects\n   */\n  integrations?: (Client | string)[];\n  /**\n   * Tools passed to the agent client\n   */\n  tools?: ToolSet;\n  /**\n   * @deprecated Use `mode: \"cua\"` instead. This option will be removed in a future version.\n   * Enables Computer Use Agent (CUA) mode.\n   */\n  cua?: boolean;\n  /**\n   * The model to use for agent functionality\n   */\n  model?: string | AgentModelConfig<string>;\n  /**\n   * The model to use for tool execution (observe/act calls within agent tools).\n   * If not specified, inherits from the main model configuration.\n   * Format: \"provider/model\" (e.g., \"openai/gpt-4o-mini\", \"google/gemini-2.0-flash-exp\")\n   */\n  executionModel?: string | AgentModelConfig<string>;\n  /**\n   * Enable streaming mode for the agent.\n   * When true, execute() returns AgentStreamResult with textStream for incremental output.\n   * When false (default), execute() returns AgentResult after completion.\n   */\n  stream?: boolean;\n  /**\n   * Tool mode for the agent. Determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n   *             for visual/screenshot-based interactions\n   * - 'cua': Uses Computer Use Agent (CUA) providers for screenshot-based automation\n   */\n  mode?: AgentToolMode;\n};\n\n/**\n * Agent instance returned when stream: true is set in AgentConfig.\n * execute() returns a streaming result that can be consumed incrementally.\n * Accepts AgentStreamExecuteOptions with streaming-specific callbacks.\n */\nexport interface StreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentStreamExecuteOptions,\n  ) => Promise<AgentStreamResult>;\n}\n\n/**\n * Agent instance returned when stream is false or not set in AgentConfig.\n * execute() returns a result after the agent completes.\n * Accepts AgentExecuteOptions with non-streaming callbacks only.\n */\nexport interface NonStreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\n// =============================================================================\n// Vision Action Tool Result Types\n// =============================================================================\n\n/**\n * Content item type for toModelOutput return values.\n * Used in tool definitions to return text and/or media to the model.\n */\nexport type ModelOutputContentItem =\n  | { type: \"text\"; text: string }\n  | { type: \"media\"; mediaType: string; data: string };\n\nexport interface ClickToolResult {\n  success: boolean;\n  describe?: string;\n  coordinates?: number[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface TypeToolResult {\n  success: boolean;\n  describe?: string;\n  text?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface DragAndDropToolResult {\n  success: boolean;\n  describe?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface FillFormField {\n  action: string;\n  value: string;\n  coordinates: { x: number; y: number };\n}\n\nexport interface FillFormVisionToolResult {\n  success: boolean;\n  playwrightArguments?: FillFormField[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface ScrollToolResult {\n  success: boolean;\n  message: string;\n  scrolledPixels: number;\n  error?: string;\n}\n\nexport interface ScrollVisionToolResult extends ScrollToolResult {\n  screenshotBase64?: string;\n}\n\nexport interface WaitToolResult {\n  success: boolean;\n  waited: number;\n  screenshotBase64?: string;\n  error?: string;\n}\n"]}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/public/agent.ts"],"names":[],"mappings":";;;AAyca,QAAA,oBAAoB,GAAG;IAClC,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,6BAA6B;IAC7B,wCAAwC;IACxC,oCAAoC;IACpC,2BAA2B;IAC3B,2BAA2B;IAC3B,6BAA6B;IAC7B,4BAA4B;IAC5B,qCAAqC;IACrC,oCAAoC;IACpC,sCAAsC;IACtC,gDAAgD;IAChD,+BAA+B;IAC/B,6BAA6B;IAC7B,mBAAmB;CACX,CAAC","sourcesContent":["import type { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport {\n  ToolSet,\n  ModelMessage,\n  wrapLanguageModel,\n  StreamTextResult,\n  StepResult,\n  PrepareStepFunction,\n  GenerateTextOnStepFinishCallback,\n  StreamTextOnStepFinishCallback,\n  StreamTextOnErrorCallback,\n  StreamTextOnChunkCallback,\n  StreamTextOnFinishCallback,\n} from \"ai\";\nimport { LogLine } from \"./logs.js\";\nimport { ClientOptions } from \"./model.js\";\nimport { StagehandZodObject } from \"../../zodCompat.js\";\nimport type { AgentEvidenceCallback } from \"./agentEvidenceEvents.js\";\n\n// Re-export ModelMessage for consumers who want to use it for conversation continuation\nexport type { ModelMessage } from \"ai\";\n\n// Re-export Tool type for consumers who want to define custom tools\nexport type { Tool } from \"ai\";\nimport { Page as PlaywrightPage } from \"playwright-core\";\nimport { Page as PuppeteerPage } from \"puppeteer-core\";\nimport { Page as PatchrightPage } from \"patchright-core\";\nimport { Page } from \"../../understudy/page.js\";\n\n// =============================================================================\n// Variable Types\n// =============================================================================\n\n/**\n * A variable value can be a simple primitive or a rich object with an optional description.\n * This unified type is shared across `act`, `agent.execute`, and other methods.\n *\n * @example Simple (backward-compatible):\n * ```typescript\n * variables: { username: \"john@example.com\" }\n * ```\n *\n * @example Rich with description (useful for agents):\n * ```typescript\n * variables: {\n *   username: { value: \"john@example.com\", description: \"The login email\" }\n * }\n * ```\n */\nexport type VariableValue =\n  | string\n  | number\n  | boolean\n  | { value: string | number | boolean; description?: string };\n\n/**\n * A collection of named variables for use in act, agent, and other methods.\n */\nexport type Variables = Record<string, VariableValue>;\n\nexport interface AgentContext {\n  options: AgentExecuteOptionsBase;\n  maxSteps: number;\n  systemPrompt: string;\n  allTools: ToolSet;\n  messages: ModelMessage[];\n  wrappedModel: ReturnType<typeof wrapLanguageModel>;\n  initialPageUrl: string;\n}\n\nexport interface AgentState {\n  collectedReasoning: string[];\n  actions: AgentAction[];\n  finalMessage: string;\n  completed: boolean;\n  currentPageUrl: string;\n}\n\nexport interface AgentAction {\n  type: string;\n  reasoning?: string;\n  taskCompleted?: boolean;\n  action?: string;\n  // Tool-specific fields\n  timeMs?: number; // wait tool\n  pageText?: string; // ariaTree tool\n  pageUrl?: string; // ariaTree tool\n  instruction?: string; // various tools\n  [key: string]: unknown;\n}\n\nexport interface AgentResult {\n  success: boolean;\n  message: string;\n  actions: AgentAction[];\n  completed: boolean;\n  metadata?: Record<string, unknown>;\n  usage?: {\n    input_tokens: number;\n    output_tokens: number;\n    reasoning_tokens?: number;\n    cached_input_tokens?: number;\n    inference_time_ms: number;\n  };\n  /**\n   * The conversation messages from this execution.\n   * Pass these to a subsequent execute() call via the `messages` option to continue the conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * Custom output data extracted based on the `output` schema provided in execute options.\n   * Only populated if an `output` schema was provided.\n   * @experimental\n   */\n  output?: Record<string, unknown>;\n}\n\nexport type AgentStreamResult = StreamTextResult<ToolSet, never> & {\n  result: Promise<AgentResult>;\n};\n\n/**\n * Base callbacks shared between execute (non-streaming) and streaming modes.\n */\nexport interface AgentCallbacks {\n  /**\n   * Optional function called before each step to modify settings.\n   * You can change the model, tool choices, active tools, system prompt,\n   * and input messages for each step.\n   */\n  prepareStep?: PrepareStepFunction<ToolSet>;\n  /**\n   * Callback called when each step (LLM call) is finished.\n   * This is called for intermediate steps as well as the final step.\n   */\n  onStepFinish?:\n    | GenerateTextOnStepFinishCallback<ToolSet>\n    | StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when Stagehand captures agent-run evidence such as\n   * screenshots, completed tool/action steps, or post-action observations.\n   */\n  onEvidence?: AgentEvidenceCallback;\n}\n\n/**\n * Error message type for streaming-only callbacks used in non-streaming mode.\n * This provides a clear error message when users try to use streaming callbacks without stream: true.\n */\ntype StreamingCallbackNotAvailable =\n  \"This callback requires 'stream: true' in AgentConfig. Set stream: true to use streaming callbacks like onChunk, onFinish, onError, and onAbort.\";\n\n/**\n * Error message for safety confirmation callback misuse.\n * Safety confirmations are only available for non-streaming CUA agent executions.\n */\ntype SafetyConfirmationCallbackNotAvailable =\n  \"Safety confirmation callbacks are only available via non-streaming AgentExecuteOptions.callbacks when using mode: 'cua'.\";\n\n/**\n * Callbacks specific to the non-streaming execute method.\n */\nexport interface AgentExecuteCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished.\n   */\n  onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback for handling safety confirmation requests from CUA providers.\n   * Only available when running an agent configured with mode: \"cua\".\n   */\n  onSafetyConfirmation?: SafetyConfirmationHandler;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onChunk:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onChunk: async (chunk) => console.log(chunk) }\n   * });\n   * ```\n   */\n  onChunk?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onFinish:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onFinish: (event) => console.log(\"Done!\", event) }\n   * });\n   * ```\n   */\n  onFinish?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onError:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onError: ({ error }) => console.error(error) }\n   * });\n   * ```\n   */\n  onError?: StreamingCallbackNotAvailable;\n\n  /**\n   * NOT AVAILABLE in non-streaming mode.\n   * This callback requires `stream: true` in AgentConfig.\n   *\n   * @example\n   * ```typescript\n   * // Enable streaming to use onAbort:\n   * const agent = stagehand.agent({ stream: true });\n   * await agent.execute({\n   *   instruction: \"...\",\n   *   callbacks: { onAbort: (event) => console.log(\"Aborted\", event.steps) }\n   * });\n   * ```\n   */\n  onAbort?: StreamingCallbackNotAvailable;\n}\n\n/**\n * Callbacks specific to the streaming mode.\n */\nexport interface AgentStreamCallbacks extends AgentCallbacks {\n  /**\n   * Callback called when each step (LLM call) is finished during streaming.\n   */\n  onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;\n  /**\n   * Callback called when an error occurs during streaming.\n   * Use this to log errors or handle error states.\n   */\n  onError?: StreamTextOnErrorCallback;\n  /**\n   * Callback called for each chunk of the stream.\n   * Stream processing will pause until the callback promise resolves.\n   */\n  onChunk?: StreamTextOnChunkCallback<ToolSet>;\n  /**\n   * Callback called when the stream finishes.\n   */\n  onFinish?: StreamTextOnFinishCallback<ToolSet>;\n  /**\n   * Callback called when the stream is aborted.\n   */\n  onAbort?: (event: {\n    steps: Array<StepResult<ToolSet>>;\n  }) => PromiseLike<void> | void;\n  /**\n   * NOT AVAILABLE in streaming mode.\n   * Safety confirmations currently require non-streaming execute() on CUA agents.\n   */\n  onSafetyConfirmation?: SafetyConfirmationCallbackNotAvailable;\n}\n\n/**\n * Base options for agent execution (without callbacks).\n */\nexport interface AgentExecuteOptionsBase {\n  instruction: string;\n  maxSteps?: number;\n  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;\n  highlightCursor?: boolean;\n  /**\n   * Previous conversation messages to continue from.\n   * Pass the `messages` from a previous AgentResult to continue that conversation.\n   * @experimental\n   */\n  messages?: ModelMessage[];\n  /**\n   * An AbortSignal that can be used to cancel the agent execution.\n   * When aborted, the agent will stop and return a partial result.\n   * @experimental\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * setTimeout(() => controller.abort(), 30000); // 30 second timeout\n   *\n   * const result = await agent.execute({\n   *   instruction: \"...\",\n   *   signal: controller.signal\n   * });\n   * ```\n   */\n  signal?: AbortSignal;\n  /**\n   * Tools to exclude from this execution.\n   * Pass an array of tool names to prevent the agent from using those tools.\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * **Available tools by mode:**\n   *\n   * **DOM mode (default):**\n   * - `act` - Perform semantic actions (click, type, etc.)\n   * - `fillForm` - Fill form fields using DOM selectors\n   * - `ariaTree` - Get accessibility tree of the page\n   * - `extract` - Extract structured data from page\n   * - `goto` - Navigate to a URL\n   * - `scroll` - Scroll using semantic directions (up/down/left/right)\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back in history\n   * - `screenshot` - Take a screenshot\n   * - `think` - Agent reasoning/planning step\n   * - `wait` - Wait for time or condition\n   * - `done` - Mark task as complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * **Hybrid mode:**\n   * - `click` - Click at specific coordinates\n   * - `type` - Type text at coordinates\n   * - `dragAndDrop` - Drag from one point to another\n   * - `clickAndHold` - Click and hold at coordinates\n   * - `fillFormVision` - Fill forms using vision/coordinates\n   * - `act` - Perform semantic actions\n   * - `ariaTree` - Get accessibility tree\n   * - `extract` - Extract data from page\n   * - `goto` - Navigate to URL\n   * - `scroll` - Scroll using coordinates\n   * - `keys` - Press keyboard keys\n   * - `navback` - Navigate back\n   * - `screenshot` - Take screenshot\n   * - `think` - Agent reasoning step\n   * - `wait` - Wait for time/condition\n   * - `done` - Mark task complete\n   * - `search` - Web search (requires useSearch: true and BROWSERBASE_API_KEY)\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * // Exclude screenshot and extract tools\n   * const result = await agent.execute({\n   *   instruction: \"Click the submit button\",\n   *   excludeTools: [\"screenshot\", \"extract\"]\n   * });\n   * ```\n   */\n  excludeTools?: string[];\n  /**\n   * A Zod schema defining custom output data to return when the task completes.\n   * The agent will populate this data in the final done tool call.\n   *\n   * @experimental\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the cheapest flight from NYC to LA\",\n   *   output: z.object({\n   *     price: z.string().describe(\"The price of the flight\"),\n   *     airline: z.string().describe(\"The airline name\"),\n   *     departureTime: z.string().describe(\"Departure time\"),\n   *   }),\n   * });\n   *\n   * console.log(result.output); // { price: \"$199\", airline: \"Delta\", departureTime: \"8:00 AM\" }\n   * ```\n   */\n  output?: StagehandZodObject;\n  /**\n   * Variables that the agent can use when filling forms or typing text.\n   * The agent will see variable names and descriptions in the system prompt,\n   * and can use them via `%variableName%` syntax in act/type/fillForm tool calls.\n   *\n   * Accepts both simple values and rich objects with descriptions (same type as `act`).\n   *\n   * **Note:** Not supported in CUA mode (`mode: \"cua\"`).\n   *\n   * @example\n   * ```typescript\n   * // Simple values\n   * variables: { username: \"john@example.com\", password: \"secret123\" }\n   *\n   * // Rich values with descriptions (helps the agent understand context)\n   * variables: {\n   *   username: { value: \"john@example.com\", description: \"The login email\" },\n   *   password: { value: \"secret123\", description: \"The login password\" },\n   * }\n   * ```\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for each agent tool call.\n   * If a tool call exceeds this duration, it will be aborted and\n   * reported back to the LLM as a timeout error so it can retry or adjust.\n   * For tools that call v3 methods (act, extract, fillForm, ariaTree), the\n   * timeout is also forwarded to the underlying v3 call for true cancellation.\n   * @default 45000 (45 seconds)\n   */\n  toolTimeout?: number;\n  /**\n   * Enable the web search tool powered by Browserbase Search API.\n   * Requires a valid Browserbase API key (BROWSERBASE_API_KEY).\n   * When set to true, the agent gains access to a `search` tool for web searches.\n   *\n   * @example\n   * ```typescript\n   * const result = await agent.execute({\n   *   instruction: \"Find the latest news about AI\",\n   *   useSearch: true,\n   * });\n   * ```\n   */\n  useSearch?: boolean;\n}\n\n/**\n * Options for non-streaming agent execution.\n * Only accepts AgentExecuteCallbacks (no streaming-specific callbacks like onChunk, onFinish).\n */\nexport interface AgentExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for non-streaming agent execution.\n   * For streaming callbacks (onChunk, onFinish, onError, onAbort), use stream: true in AgentConfig.\n   */\n  callbacks?: AgentExecuteCallbacks;\n}\n\n/**\n * Options for streaming agent execution.\n * Accepts AgentStreamCallbacks including onChunk, onFinish, onError, and onAbort.\n */\nexport interface AgentStreamExecuteOptions extends AgentExecuteOptionsBase {\n  /**\n   * Callbacks for streaming agent execution.\n   * Includes streaming-specific callbacks: onChunk, onFinish, onError, onAbort.\n   */\n  callbacks?: AgentStreamCallbacks;\n}\nexport type AgentType =\n  | \"openai\"\n  | \"anthropic\"\n  | \"google\"\n  | \"microsoft\"\n  | \"bedrock\"\n  | \"vertex\"\n  | \"azure\";\n\nexport const AVAILABLE_CUA_MODELS = [\n  \"openai/gpt-5.4\",\n  \"openai/gpt-5.4-mini\",\n  \"openai/gpt-5.5\",\n  \"openai/computer-use-preview\",\n  \"openai/computer-use-preview-2025-03-11\",\n  \"anthropic/claude-opus-4-5-20251101\",\n  \"anthropic/claude-opus-4-6\",\n  \"anthropic/claude-opus-4-8\",\n  \"anthropic/claude-sonnet-4-6\",\n  \"anthropic/claude-haiku-4-5\",\n  \"anthropic/claude-haiku-4-5-20251001\",\n  \"anthropic/claude-sonnet-4-20250514\",\n  \"anthropic/claude-sonnet-4-5-20250929\",\n  \"google/gemini-2.5-computer-use-preview-10-2025\",\n  \"google/gemini-3-flash-preview\",\n  \"google/gemini-3-pro-preview\",\n  \"microsoft/fara-7b\",\n] as const;\nexport type AvailableCuaModel = (typeof AVAILABLE_CUA_MODELS)[number];\n\nexport interface AgentExecutionOptions<\n  TOptions extends AgentExecuteOptions = AgentExecuteOptions,\n> {\n  options: TOptions;\n  logger: (message: LogLine) => void;\n  retries?: number;\n}\n\nexport interface AgentHandlerOptions {\n  modelName: string;\n  clientOptions?: ClientOptions;\n  userProvidedInstructions?: string;\n  experimental?: boolean;\n}\n\nexport interface ActionExecutionResult {\n  success: boolean;\n  error?: string;\n  data?: unknown;\n}\n\n/**\n * Represents a safety check that requires user confirmation before proceeding.\n * These are issued by CUA providers (OpenAI, Google) when the agent attempts\n * potentially risky actions.\n */\nexport interface SafetyCheck {\n  /** Unique identifier for this safety check */\n  id: string;\n  /** Code identifying the type of safety concern */\n  code: string;\n  /** Human-readable description of the safety concern */\n  message: string;\n}\n\n/**\n * Response from the user for a safety confirmation request.\n */\nexport interface SafetyConfirmationResponse {\n  /** Whether the user acknowledged/approved the safety checks */\n  acknowledged: boolean;\n}\n\n/**\n * Callback for handling safety confirmation requests.\n * Called when the CUA provider issues safety checks that require user confirmation.\n * The callback should return a promise that resolves when the user has made a decision.\n *\n * @param safetyChecks - Array of safety checks requiring confirmation\n * @returns Promise resolving to the user's response\n *\n * @example\n * ```typescript\n * const agent = stagehand.agent({\n *   mode: \"cua\",\n * });\n * await agent.execute({\n *   instruction: \"...\",\n *   callbacks: {\n *     onSafetyConfirmation: async (checks) => {\n *       console.log(\"Safety checks:\", checks);\n *       const userApproved = await showConfirmationDialog(checks);\n *       return { acknowledged: userApproved };\n *     },\n *   },\n * });\n * ```\n */\nexport type SafetyConfirmationHandler = (\n  safetyChecks: SafetyCheck[],\n) => Promise<SafetyConfirmationResponse>;\n\n// Anthropic types:\n\nexport interface ToolUseItem extends ResponseItem {\n  type: \"tool_use\";\n  id: string; // This is the correct property name from Anthropic's API\n  name: string; // Name of the tool being used\n  input: Record<string, unknown>;\n}\n\nexport interface AnthropicMessage {\n  role: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\nexport interface AnthropicContentBlock {\n  type: string;\n  [key: string]: unknown;\n}\n\nexport interface AnthropicTextBlock extends AnthropicContentBlock {\n  type: \"text\";\n  text: string;\n}\n\nexport interface AnthropicToolResult {\n  type: \"tool_result\";\n  tool_use_id: string;\n  content: string | Array<AnthropicContentBlock>;\n}\n\n// OpenAI types:\n\nexport interface ResponseItem {\n  type: string;\n  id: string;\n  [key: string]: unknown;\n}\n\nexport interface ComputerCallItem extends ResponseItem {\n  type: \"computer_call\";\n  call_id: string;\n  action?: {\n    type: string;\n    [key: string]: unknown;\n  };\n  actions?: Array<{\n    type: string;\n    [key: string]: unknown;\n  }>;\n  pending_safety_checks?: Array<{\n    id: string;\n    code: string;\n    message: string;\n  }>;\n}\n\nexport interface FunctionCallItem extends ResponseItem {\n  type: \"function_call\";\n  call_id: string;\n  name: string;\n  arguments: string;\n}\n\nexport type ResponseInputItem =\n  | { role: string; content: string }\n  | {\n      type: \"computer_call_output\";\n      call_id: string;\n      output:\n        | {\n            type: \"input_image\" | \"computer_screenshot\";\n            image_url: string;\n            detail?: \"original\" | \"high\" | \"low\";\n            current_url?: string;\n            error?: string;\n            [key: string]: unknown;\n          }\n        | string;\n      acknowledged_safety_checks?: Array<{\n        id: string;\n        code: string;\n        message: string;\n      }>;\n    }\n  | {\n      type: \"function_call_output\";\n      call_id: string;\n      output: string;\n    };\n\nexport interface AgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\nexport type AgentProviderType = AgentType;\n\nexport type AgentModelConfig<TModelName extends string = string> = {\n  modelName: TModelName;\n} & Record<string, unknown>;\n\n/**\n * Agent tool mode determines which set of tools are available to the agent.\n * - 'dom': Uses DOM-based tools (act, fillForm) - better for structured page interactions\n * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - better for visual/screenshot-based interactions\n * - 'cua': Uses Computer Use Agent (CUA) providers like Anthropic Claude or Google Gemini for screenshot-based automation\n */\nexport type AgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\nexport type AgentConfig = {\n  /**\n   * Custom system prompt to provide to the agent. Overrides the default system prompt.\n   */\n  systemPrompt?: string;\n  /**\n   * MCP integrations - Array of Client objects\n   */\n  integrations?: (Client | string)[];\n  /**\n   * Tools passed to the agent client\n   */\n  tools?: ToolSet;\n  /**\n   * @deprecated Use `mode: \"cua\"` instead. This option will be removed in a future version.\n   * Enables Computer Use Agent (CUA) mode.\n   */\n  cua?: boolean;\n  /**\n   * The model to use for agent functionality\n   */\n  model?: string | AgentModelConfig<string>;\n  /**\n   * The model to use for tool execution (observe/act calls within agent tools).\n   * If not specified, inherits from the main model configuration.\n   * Format: \"provider/model\" (e.g., \"openai/gpt-4o-mini\", \"google/gemini-2.0-flash-exp\")\n   */\n  executionModel?: string | AgentModelConfig<string>;\n  /**\n   * Enable streaming mode for the agent.\n   * When true, execute() returns AgentStreamResult with textStream for incremental output.\n   * When false (default), execute() returns AgentResult after completion.\n   */\n  stream?: boolean;\n  /**\n   * Tool mode for the agent. Determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n   *             for visual/screenshot-based interactions\n   * - 'cua': Uses Computer Use Agent (CUA) providers for screenshot-based automation\n   */\n  mode?: AgentToolMode;\n};\n\n/**\n * Agent instance returned when stream: true is set in AgentConfig.\n * execute() returns a streaming result that can be consumed incrementally.\n * Accepts AgentStreamExecuteOptions with streaming-specific callbacks.\n */\nexport interface StreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentStreamExecuteOptions,\n  ) => Promise<AgentStreamResult>;\n}\n\n/**\n * Agent instance returned when stream is false or not set in AgentConfig.\n * execute() returns a result after the agent completes.\n * Accepts AgentExecuteOptions with non-streaming callbacks only.\n */\nexport interface NonStreamingAgentInstance {\n  execute: (\n    instructionOrOptions: string | AgentExecuteOptions,\n  ) => Promise<AgentResult>;\n}\n\n// =============================================================================\n// Vision Action Tool Result Types\n// =============================================================================\n\n/**\n * Content item type for toModelOutput return values.\n * Used in tool definitions to return text and/or media to the model.\n */\nexport type ModelOutputContentItem =\n  | { type: \"text\"; text: string }\n  | { type: \"media\"; mediaType: string; data: string };\n\nexport interface ClickToolResult {\n  success: boolean;\n  describe?: string;\n  coordinates?: number[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface TypeToolResult {\n  success: boolean;\n  describe?: string;\n  text?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface DragAndDropToolResult {\n  success: boolean;\n  describe?: string;\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface FillFormField {\n  action: string;\n  value: string;\n  coordinates: { x: number; y: number };\n}\n\nexport interface FillFormVisionToolResult {\n  success: boolean;\n  playwrightArguments?: FillFormField[];\n  error?: string;\n  screenshotBase64?: string;\n}\n\nexport interface ScrollToolResult {\n  success: boolean;\n  message: string;\n  scrolledPixels: number;\n  error?: string;\n}\n\nexport interface ScrollVisionToolResult extends ScrollToolResult {\n  screenshotBase64?: string;\n}\n\nexport interface WaitToolResult {\n  success: boolean;\n  waited: number;\n  screenshotBase64?: string;\n  error?: string;\n}\n"]}