@intuned/browser-use-dev 0.0.0-stage → 0.1.2-dev.0

package/LICENSE

@@ -0,0 +1,43 @@
+Acceptance
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+No Liability
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+Definitions
+The licensor is the entity offering these terms, and the software is the software the licensor makes available under these terms, including any portion of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.
+

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @intuned/browser-use
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Intuned SDK browser-use agent (BETA): drive a Playwright page with any
+vision-capable model — screenshots in, click/type/scroll actions out, executed
+on the exact page you pass in. Built on the AI SDK, routed through the Intuned
+AI gateway (or a direct provider API key).
+
+```typescript
+import { executeTask } from "@intuned/browser-use";
+
+const result = await executeTask({
+  page,
+  task: "Scroll down until the year 2021 is visible and report the first 2021 entry's title.",
+  maxTurns: 20,
+  timeoutInMs: 120_000,
+});
+console.log(result.finalText, result.totalCostInCents);
+```
+
+## Highlights
+
+- **Reliable interactions**: every action syncs the viewport to the real
+  window size first, waits for the network it triggers to settle, and scrolls
+  slowly in steps so lazy-loaded content renders instead of being skipped.
+- **Browser-event awareness**: file downloads, popup tabs opening, and tabs
+  closing during an action are detected and reported back to the model,
+  alongside the current URL.
+- **Structured results**: pass an `outputSchema` (JSON schema) and get a
+  schema-validated `output` object back.
+- **Extensible**: add your own function tools via `tools`; opt into the
+  `execute_javascript` escape hatch with `enableJavaScriptTool`.
+
+## Development
+
+```bash
+yarn install
+yarn build   # tsc + babel into dist/
+yarn test    # vitest
+yarn lint
+```

package/dist/browser-use/errors.js

@@ -0,0 +1,15 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.BrowserUseError = void 0;
+class BrowserUseError extends Error {
+  constructor(message, info) {
+    super(message);
+    this.name = "BrowserUseError";
+    this.totalCostInCents = info.totalCostInCents;
+    this.turns = info.turns;
+  }
+}
+exports.BrowserUseError = BrowserUseError;

package/dist/browser-use/eventCollector.js

@@ -0,0 +1,96 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EventCollector = void 0;
+const EVENT_WAIT_TIMEOUT_MS = 3_000;
+function timestamp() {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+function deferred() {
+  const d = {
+    done: false
+  };
+  d.promise = new Promise(resolve => {
+    d.resolve = () => {
+      d.done = true;
+      resolve();
+    };
+  });
+  return d;
+}
+class EventCollector {
+  _context = null;
+  _events = [];
+  _trackedPages = [];
+  _newPage = deferred();
+  _download = deferred();
+  _close = deferred();
+  _onNewPage = page => {
+    this._newPage.resolve();
+    this._events.push(`Open Page Event (In New Tab) Detected with url: ${page.url()} at ${timestamp()}`);
+    page.on("close", this._onPageClose);
+    page.on("download", this._onDownload);
+    this._trackedPages.push(page);
+  };
+  _onPageClose = page => {
+    this._close.resolve();
+    this._events.push(`Close Page Event Detected with url: ${page.url()} at ${timestamp()}`);
+  };
+  _onDownload = download => {
+    this._download.resolve();
+    this._events.push(`Download Event Detected with file name: ${download.suggestedFilename()} at ${timestamp()}`);
+  };
+  constructor(page) {
+    this._page = page;
+  }
+  start() {
+    this._context = this._page.context();
+    this._context.on("page", this._onNewPage);
+    this._page.on("close", this._onPageClose);
+    this._page.on("download", this._onDownload);
+    this._trackedPages.push(this._page);
+  }
+  async stop() {
+    var _this$_context;
+    const pending = [this._newPage, this._download, this._close].filter(d => !d.done).map(d => d.promise);
+    if (pending.length > 0) {
+      let timer;
+      await Promise.race([Promise.all(pending), new Promise(resolve => {
+        timer = setTimeout(resolve, EVENT_WAIT_TIMEOUT_MS);
+      })]);
+      if (timer !== undefined) clearTimeout(timer);
+    }
+    for (const page of this._trackedPages.slice(1)) {
+      try {
+        const index = this._page.context().pages().indexOf(page);
+        if (index !== -1) {
+          this._events.push(`New tab available at index ${index} with url: ${page.url()}`);
+        }
+      } catch {}
+    }
+    (_this$_context = this._context) === null || _this$_context === void 0 || _this$_context.off("page", this._onNewPage);
+    for (const page of this._trackedPages) {
+      page.off("close", this._onPageClose);
+      page.off("download", this._onDownload);
+    }
+  }
+  getEvents() {
+    return [...this._events];
+  }
+  _eventsString() {
+    return this._events.length > 0 ? this._events.join("\n") : "No events detected";
+  }
+  _currentUrl() {
+    try {
+      return this._page.url();
+    } catch {
+      return "unknown";
+    }
+  }
+  formatResponse(actionResult) {
+    return `CURRENT URL: ${this._currentUrl()}\nResult: ${actionResult}\nEvents: ${this._eventsString()}`;
+  }
+}
+exports.EventCollector = EventCollector;

package/dist/browser-use/executeTask.js

@@ -0,0 +1,242 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.executeTask = void 0;
+var _dotenv = require("dotenv");
+var _ai = require("ai");
+var _Logger = require("../common/Logger");
+var _aiGateway = require("../common/aiGateway");
+var _parseCostInCents = require("../common/parseCostInCents");
+var _playwrightComputer = require("./playwrightComputer");
+var _messages = require("./messages");
+var _prompts = require("./prompts");
+var _tools = require("./tools");
+var _errors = require("./errors");
+(0, _dotenv.config)();
+const DEFAULT_MODEL = "gpt-5.6-luna";
+const DEFAULT_MAX_TURNS = 100;
+const MAX_IMAGES_IN_CONTEXT = 10;
+const RESULT_NUDGE_TEXT = `You finished without calling the \`${_tools.RESULT_TOOL_NAME}\` tool. ` + `Call \`${_tools.RESULT_TOOL_NAME}\` now with the final result of the task.`;
+function logErrorCauseChain(error) {
+  let current = error;
+  for (let depth = 0; current instanceof Error && depth < 5; depth++) {
+    const e = current;
+    const extras = [e.url ? `url=${e.url}` : "", e.statusCode !== undefined ? `status=${e.statusCode}` : "", typeof e.responseBody === "string" ? `body=${e.responseBody.slice(0, 800)}` : ""].filter(Boolean).join(" ");
+    _Logger.logger.error(`[browser-use] ${depth === 0 ? "error" : `cause[${depth}]`}: ${e.name}: ${String(e.message).slice(0, 800)}${extras ? ` (${extras})` : ""}`);
+    current = e.cause;
+  }
+}
+function sanitizeMessages(messages) {
+  return messages.map(message => {
+    if (!Array.isArray(message.content)) return message;
+    return {
+      ...message,
+      content: message.content.map(part => {
+        if (part.type === "image") return {
+          ...part,
+          image: "[omitted]"
+        };
+        const output = part.output;
+        if (part.type === "tool-result" && (output === null || output === void 0 ? void 0 : output.type) === "content" && Array.isArray(output.value)) {
+          return {
+            ...part,
+            output: {
+              ...output,
+              value: output.value.map(item => item.type === "media" ? {
+                ...item,
+                data: "[omitted]"
+              } : item)
+            }
+          };
+        }
+        return part;
+      })
+    };
+  });
+}
+const executeTask = async options => {
+  const {
+    page,
+    model = DEFAULT_MODEL,
+    apiKey,
+    tools: extraTools,
+    logSteps = true,
+    enableJavaScriptTool = false,
+    task,
+    systemPrompt,
+    outputSchema,
+    maxTurns = DEFAULT_MAX_TURNS,
+    timeoutInMs,
+    signal,
+    showImages = false
+  } = options;
+  if (!task || task.trim().length === 0) {
+    throw new Error("browser-use: executeTask requires a non-empty task");
+  }
+  if (logSteps) _Logger.logger.info(`[browser-use] Executing task. Selected model: ${model}`);
+  const computer = new _playwrightComputer.PlaywrightComputer(page);
+  let outputCaptured = false;
+  let capturedOutput = null;
+  let costSoFarCents = 0;
+  let turnsSoFar = 0;
+  const usage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0
+  };
+  const tools = (0, _tools.buildTools)({
+    computer,
+    extraTools,
+    outputSchema,
+    logSteps,
+    enableJavaScriptTool,
+    onResultCaptured: result => {
+      outputCaptured = true;
+      capturedOutput = result;
+    }
+  });
+  const providerInstance = await (0, _aiGateway.createProviderInstance)({
+    apiKey,
+    model
+  });
+  const responses = providerInstance.responses;
+  const usesResponsesApi = typeof responses === "function";
+  const languageModel = typeof responses === "function" ? responses(model) : providerInstance.chat(model);
+  const parts = [(0, _prompts.composeDefaultSystemPrompt)()];
+  if (systemPrompt) parts.push(systemPrompt);
+  if (outputSchema) {
+    parts.push(["<RESULT_SUBMISSION>", `- When the task is complete, call the \`${_tools.RESULT_TOOL_NAME}\` tool exactly once with the final result.`, "- Submit the result via the tool; do not put it only in your text reply.", "</RESULT_SUBMISSION>"].join("\n"));
+  }
+  const system = parts.join("\n\n");
+  const initialScreenshot = await computer.screenshot();
+  const initialMessages = [{
+    role: "user",
+    content: [{
+      type: "text",
+      text: task
+    }, {
+      type: "image",
+      image: `data:image/png;base64,${initialScreenshot}`
+    }]
+  }];
+  const abort = new AbortController();
+  const onExternalAbort = () => abort.abort();
+  if (signal) {
+    if (signal.aborted) abort.abort();else signal.addEventListener("abort", onExternalAbort, {
+      once: true
+    });
+  }
+  const runStep = async (messages, remainingTurns) => (0, _ai.generateText)({
+    model: languageModel,
+    system,
+    messages,
+    tools,
+    providerOptions: {
+      ...(usesResponsesApi ? {
+        openai: {
+          reasoningSummary: "auto"
+        }
+      } : {}),
+      ...((0, _aiGateway.detectProvider)(model) === "anthropic" ? {
+        anthropic: {
+          cacheControl: {
+            type: "ephemeral"
+          }
+        }
+      } : {})
+    },
+    stopWhen: [(0, _ai.stepCountIs)(remainingTurns), () => outputCaptured],
+    prepareStep: ({
+      messages
+    }) => {
+      const pruned = (0, _messages.pruneImages)(messages, MAX_IMAGES_IN_CONTEXT);
+      return pruned === messages ? undefined : {
+        messages: pruned
+      };
+    },
+    abortSignal: abort.signal,
+    onStepFinish: step => {
+      var _step$usage, _step$usage2, _step$usage3, _step$response;
+      turnsSoFar += 1;
+      usage.inputTokens += ((_step$usage = step.usage) === null || _step$usage === void 0 ? void 0 : _step$usage.inputTokens) ?? 0;
+      usage.outputTokens += ((_step$usage2 = step.usage) === null || _step$usage2 === void 0 ? void 0 : _step$usage2.outputTokens) ?? 0;
+      usage.totalTokens += ((_step$usage3 = step.usage) === null || _step$usage3 === void 0 ? void 0 : _step$usage3.totalTokens) ?? 0;
+      costSoFarCents += (0, _parseCostInCents.parseCostInCents)((_step$response = step.response) === null || _step$response === void 0 || (_step$response = _step$response.headers) === null || _step$response === void 0 ? void 0 : _step$response["x-ai-cost-in-cents"]);
+      if (logSteps) {
+        var _step$text, _reasoningText;
+        const text = (_step$text = step.text) === null || _step$text === void 0 ? void 0 : _step$text.trim();
+        if (text) _Logger.logger.info(`[browser-use] agent: ${text}`);
+        const reasoning = (_reasoningText = step.reasoningText) === null || _reasoningText === void 0 ? void 0 : _reasoningText.trim();
+        if (reasoning && reasoning !== text) {
+          _Logger.logger.info(`[browser-use] agent (reasoning): ${reasoning.slice(0, 600)}${reasoning.length > 600 ? "…" : ""}`);
+        }
+      }
+    }
+  });
+  let timer;
+  try {
+    const runPromise = runStep(initialMessages, maxTurns);
+    let result = timeoutInMs === undefined ? await runPromise : await Promise.race([runPromise, new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        abort.abort();
+        reject(new _errors.BrowserUseError(`browser-use agent timed out after ${timeoutInMs}ms`, {
+          totalCostInCents: costSoFarCents,
+          turns: turnsSoFar
+        }));
+      }, timeoutInMs);
+    })]);
+    const stillWantsToContinue = result.finishReason === "tool-calls";
+    if (result.steps.length >= maxTurns && stillWantsToContinue && !outputCaptured) {
+      throw new _errors.BrowserUseError(`browser-use agent exceeded ${maxTurns} turns without finishing`, {
+        totalCostInCents: costSoFarCents,
+        turns: turnsSoFar
+      });
+    }
+    if (outputSchema && !outputCaptured && !stillWantsToContinue && result.steps.length < maxTurns) {
+      if (logSteps) _Logger.logger.info(`[browser-use] nudging the agent to submit the structured result`);
+      const nudgeMessages = [...initialMessages, ...result.response.messages, {
+        role: "user",
+        content: [{
+          type: "text",
+          text: RESULT_NUDGE_TEXT
+        }]
+      }];
+      const remainingTurns = maxTurns - result.steps.length;
+      const nudgeResult = await runStep(nudgeMessages, remainingTurns);
+      if (nudgeResult.steps.length >= remainingTurns && nudgeResult.finishReason === "tool-calls" && !outputCaptured) {
+        throw new _errors.BrowserUseError(`browser-use agent exceeded ${maxTurns} turns without finishing`, {
+          totalCostInCents: costSoFarCents,
+          turns: turnsSoFar
+        });
+      }
+      result = {
+        ...result,
+        text: nudgeResult.text,
+        finishReason: nudgeResult.finishReason,
+        response: nudgeResult.response,
+        steps: [...result.steps, ...nudgeResult.steps]
+      };
+    }
+    if (logSteps) {
+      _Logger.logger.info(`[browser-use] run finished after ${turnsSoFar} turns. Total AI Cost In Cents: ${costSoFarCents.toFixed(2)}`);
+    }
+    const allMessages = [...initialMessages, ...result.response.messages];
+    return {
+      finalText: result.text,
+      messages: showImages ? allMessages : sanitizeMessages(allMessages),
+      output: outputCaptured ? capturedOutput : null,
+      totalCostInCents: costSoFarCents,
+      turns: turnsSoFar,
+      usage
+    };
+  } catch (e) {
+    if (logSteps && !(e instanceof _errors.BrowserUseError)) logErrorCauseChain(e);
+    throw e;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal) signal.removeEventListener("abort", onExternalAbort);
+  }
+};
+exports.executeTask = executeTask;

package/dist/browser-use/export.d.ts

@@ -0,0 +1,228 @@
+import { Page } from "playwright";
+import { ModelMessage } from "ai";
+
+/**
+ * A caller-supplied function tool the browser-use model can invoke during a
+ * run, alongside the built-in `computer`, `list_tabs`, `clear_field` and `fill_field`
+ * tools. The handler's return value is serialized and fed back to the model
+ * as the tool output ("success" when it returns nothing); a thrown error is
+ * fed back as an `error: ...` output the model can react to.
+ *
+ * @interface BrowserUseFunctionTool
+ */
+export interface BrowserUseFunctionTool {
+  /** Tool name the model calls it by. Must not collide with built-in tools. */
+  name: string;
+  /** What the tool does and when the model should use it. */
+  description: string;
+  /** JSON schema object describing the tool's arguments. */
+  parameters: Record<string, unknown>;
+  /** Executes the tool call with the model-provided arguments. */
+  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+
+/**
+ * A debug frame captured immediately BEFORE a mouse action executes, with the
+ * action's target point(s) so a recording shows exactly where each action
+ * landed on the state the model acted on.
+ *
+ * @interface BrowserUseFrame
+ */
+export interface BrowserUseFrame {
+  /** PNG screenshot, one pixel per CSS pixel. */
+  image: Buffer;
+  /** Screenshot width in CSS pixels. */
+  width: number;
+  /** Screenshot height in CSS pixels. */
+  height: number;
+  /** The action about to run (e.g. "click", "drag", "clear_field"). */
+  action: string;
+  /** The action's target coordinate(s) in CSS pixels. */
+  markers: { x: number; y: number }[];
+  /** Extra action context (e.g. mouse button, scroll deltas). */
+  label: string;
+}
+
+/**
+ * Options for {@link executeTask}.
+ *
+ * @interface ExecuteTaskOptions
+ */
+export interface ExecuteTaskOptions {
+  /** The Playwright page the agent acts on. The agent stays pinned to this
+   * exact page for screenshots and actions (it never switches tabs). */
+  page: Page;
+  /** Model id to drive the run. Any vision-capable model id supported by the
+   * SDK's AI gateway (Anthropic, OpenAI, Google) — the provider is detected
+   * from the id. Defaults to "gpt-5.6-luna". */
+  model?: string;
+  /** Explicit API key for the detected provider. When omitted, the
+   * provider's env var (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` /
+   * `GOOGLE_API_KEY`) is used; when that is also absent, the Intuned AI
+   * gateway (via `@intuned/runtime`) provides credentials. */
+  apiKey?: string;
+  /** Extra function tools the model may call during the run. */
+  tools?: BrowserUseFunctionTool[];
+  /** Log each model message, tool call, and request cost. Defaults to true. */
+  logSteps?: boolean;
+  /** Expose the built-in `execute_javascript` tool, letting the model run
+   * arbitrary JavaScript in the page and get its result back — an escape
+   * hatch for cases the standard actions can't reach. Disabled by default. */
+  enableJavaScriptTool?: boolean;
+  /** The task for the agent, in plain English. Scope it tightly — say exactly
+   * what to act on and what outcome is expected. */
+  task: string;
+  /** Appended (after a blank line) to the built-in system prompt — the place
+   * for caller-specific rules the agent must follow at system priority. The
+   * built-in prompt (browser capability + viewport size + full-autonomy
+   * framing) is always present and never replaced, so callers only supply
+   * what's specific to them. */
+  systemPrompt?: string;
+  /** JSON schema for a structured result of the run. When provided, the
+   * model gets a reserved `submit_result` tool with these parameters and is
+   * instructed to call it once when the task is done; the submission is
+   * validated against the schema (an invalid one is sent back for the model
+   * to correct), and the validated object is returned as the result's
+   * `output`. If the model finishes without submitting, it is nudged once;
+   * `output` is null when it still doesn't submit. Reserves the tool name
+   * "submit_result". */
+  outputSchema?: Record<string, unknown>;
+  /** Model-call cap; the run throws when exceeded (runaway guard).
+   * Defaults to 100. */
+  maxTurns?: number;
+  /** Overall wall-clock cap for the run. On expiry the loop is aborted (no
+   * further page actions) and the returned promise rejects. */
+  timeoutInMs?: number;
+  /** External abort signal; aborting stops the loop between model calls and
+   * before each page action. */
+  signal?: AbortSignal;
+  /** Keep raw screenshots in the returned `messages` instead of replacing
+   * them with "[omitted]". Defaults to false. */
+  showImages?: boolean;
+}
+
+/**
+ * Result of a completed {@link executeTask} run.
+ *
+ * @interface BrowserUseTurnResult
+ */
+export interface BrowserUseTurnResult<TOutput = unknown> {
+  /** The final text of the model's last assistant message ("" when none). */
+  finalText: string;
+  /** The full run transcript (screenshots omitted unless `showImages`). */
+  messages: ModelMessage[];
+  /** The schema-validated structured result the model submitted via the
+   * `submit_result` tool (see `outputSchema`). Null when no `outputSchema`
+   * was given or the model never submitted a valid result. */
+  output: TOutput | null;
+  /** Summed per-request cost of the run in cents, read from the Intuned AI
+   * gateway's `x-ai-cost-in-cents` response header (0 when unavailable,
+   * e.g. when calling a provider directly). */
+  totalCostInCents: number;
+  /** Number of model calls the run made. */
+  turns: number;
+  /** Token usage summed over the run's model calls (input, output, and total tokens). */
+  usage: { inputTokens: number; outputTokens: number; totalTokens: number };
+}
+
+/**
+ * Run a browser-use agent (BETA) that drives a Playwright page: screenshots
+ * in, click/type/scroll actions out, executed on the exact page you pass in.
+ * Built on the AI SDK, so any vision-capable model the SDK's AI gateway
+ * supports (Anthropic, OpenAI, Google) can drive the browser — not just
+ * models with a provider-specific "computer use" tool.
+ *
+ * ## Features and limitations
+ * - Composes the system and user messages for you — pass a plain-English
+ *   `task` (and optionally extra system-priority rules via `systemPrompt`).
+ * - Structured results: pass an `outputSchema` (JSON schema) and the run
+ *   returns a schema-validated `output` object the model submits via a
+ *   reserved `submit_result` tool when the task is done.
+ * - Built-in function tools beyond the standard actions (click, double_click,
+ *   scroll, type, keypress, wait, move, drag): `screenshot` (see the page),
+ *   `list_tabs` (check whether a popup tab opened), `clear_field`
+ *   (deterministically empty an input) and `fill_field` (click, clear and
+ *   type into a field in one action). Add your own via `tools`.
+ * - Every action reports the browser events it triggered — file downloads,
+ *   popup tabs opening or closing — plus the current URL back to the model,
+ *   so out-of-viewport side effects aren't invisible.
+ * - Actions return text and run one at a time in the order the model issued
+ *   them; the agent calls `screenshot` to see the page (`scroll` and `wait`
+ *   return one). Screenshots are one pixel per CSS pixel, viewport-synced, so
+ *   model coordinates and mouse coordinates share one space — safe on HiDPI
+ *   headful browsers.
+ * - Actions wait for the network they trigger to settle, and scrolling is
+ *   slow and stepped so lazy-loaded content renders instead of being skipped.
+ * - Credentials resolve like the rest of the SDK: explicit `apiKey`, else
+ *   the provider's env var, else the Intuned AI gateway. Per-request gateway
+ *   cost is summed into the result's `totalCostInCents`.
+ * - BETA: the API surface may change between minor versions.
+ *
+ * @param {ExecuteTaskOptions} options - Task and agent configuration.
+ * @returns {Promise<BrowserUseTurnResult>} The completed run's result.
+ * @example
+ * ```typescript Run a task on the current page
+ * import { executeTask } from "@intuned/browser-use";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext) {
+ *   await page.goto("https://sandbox.intuned.dev/infinite-scroll");
+ *   const result = await executeTask({
+ *     page,
+ *     task: "Scroll down until the year 2021 is visible and report the first 2021 entry's title.",
+ *     maxTurns: 20,
+ *     timeoutInMs: 120_000,
+ *   });
+ *   return { answer: result.finalText, costInCents: result.totalCostInCents };
+ * }
+ * ```
+ * @example
+ * ```typescript Custom tool and system prompt
+ * import { executeTask } from "@intuned/browser-use";
+ * import { BrowserContext, Page } from "playwright";
+ *
+ * interface Params {}
+ *
+ * export default async function handler(params: Params, page: Page, context: BrowserContext) {
+ *   const result = await executeTask({
+ *     page,
+ *     task: "Use the get_reference_code tool, type the code into the Lookup field, and click Search.",
+ *     systemPrompt:
+ *       "- Act ONLY on the current screen of the active tab. Never navigate to another URL.",
+ *     tools: [
+ *       {
+ *         name: "get_reference_code",
+ *         description: "Get the reference code to type into the lookup field.",
+ *         parameters: { type: "object", properties: {}, additionalProperties: false, required: [] },
+ *         handler: () => ({ code: "REF-1234" }),
+ *       },
+ *     ],
+ *   });
+ *   return { answer: result.finalText };
+ * }
+ * ```
+ */
+export declare function executeTask<TOutput = unknown>(
+  options: ExecuteTaskOptions
+): Promise<BrowserUseTurnResult<TOutput>>;
+
+/**
+ * Thrown when a run doesn't finish cleanly (timeout or maxTurns exceeded).
+ * Carries spend/progress up to the point of failure — the ONLY way to read
+ * it in these cases, since there is no persistent agent object to poll and
+ * no successful {@link BrowserUseTurnResult} to return.
+ *
+ * @class BrowserUseError
+ */
+export declare class BrowserUseError extends Error {
+  /** Accumulated cost (in cents) up to the point of failure. */
+  readonly totalCostInCents: number;
+  /** Model calls completed before the failure. */
+  readonly turns: number;
+  constructor(
+    message: string,
+    info: { totalCostInCents: number; turns: number }
+  );
+}