@anvia/browser 1.0.0-rc.10

package/dist/index.js

@@ -0,0 +1,1026 @@
+// src/docker-browser.ts
+import { fileURLToPath } from "url";
+
+// src/connection.ts
+import { randomUUID } from "crypto";
+import { chromium } from "playwright-core";
+
+// src/errors.ts
+var BrowserError = class extends Error {
+  constructor(message, code, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "BrowserError";
+  }
+  code;
+};
+
+// src/connection.ts
+async function connectPlaywrightBrowser(options) {
+  options.abortSignal?.throwIfAborted();
+  const browser = await chromium.connectOverCDP(options.endpointUrl);
+  if (options.abortSignal?.aborted) {
+    await browser.close().catch(() => void 0);
+    options.abortSignal.throwIfAborted();
+  }
+  return new PlaywrightBrowserConnectionImpl(browser, options.control);
+}
+var PlaywrightBrowserConnectionImpl = class {
+  browser;
+  control;
+  tabIds = /* @__PURE__ */ new WeakMap();
+  selected;
+  isClosed = false;
+  actionTail = Promise.resolve();
+  navigationPolicyKey;
+  navigationGuard = Promise.resolve();
+  constructor(browser, control) {
+    this.browser = browser;
+    this.control = control;
+    this.selected = this.pages()[0];
+    this.browser.once("disconnected", () => {
+      this.isClosed = true;
+    });
+  }
+  get closed() {
+    return this.isClosed || !this.browser.isConnected();
+  }
+  async listTabs() {
+    return this.runAction(void 0, () => this.tabSummaries());
+  }
+  async tabSummaries() {
+    return Object.freeze(
+      await Promise.all(
+        this.pages().map(
+          async (page) => Object.freeze({
+            id: this.idFor(page),
+            title: await page.title(),
+            url: page.url(),
+            selected: page === this.selected
+          })
+        )
+      )
+    );
+  }
+  async runAction(abortSignal, operation) {
+    const previous = this.actionTail;
+    let release;
+    this.actionTail = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      this.assertOpen();
+      await this.navigationGuard;
+      return await this.control.runAgentAction(() => this.withAbort(abortSignal, operation));
+    } finally {
+      release?.();
+    }
+  }
+  setNavigationPolicy(policy) {
+    this.assertOpen();
+    const key = JSON.stringify(policy);
+    if (this.navigationPolicyKey !== void 0) {
+      if (this.navigationPolicyKey !== key) {
+        throw new TypeError("Browser connection already has a different navigation policy.");
+      }
+      return;
+    }
+    this.navigationPolicyKey = key;
+    const routeHandler = (route) => enforceNavigationPolicy(route, policy);
+    this.navigationGuard = Promise.all(
+      this.browser.contexts().map((context) => context.route("**/*", routeHandler))
+    ).then(() => void 0);
+    void this.navigationGuard.catch(() => void 0);
+  }
+  selectedPage() {
+    this.assertOpen();
+    if (this.selected !== void 0 && !this.selected.isClosed()) return this.selected;
+    const page = this.pages()[0];
+    if (page === void 0) {
+      throw new BrowserError("Browser has no open tabs.", "invalid_state");
+    }
+    this.selected = page;
+    return page;
+  }
+  async openTab() {
+    const context = this.browser.contexts()[0];
+    if (context === void 0) {
+      throw new BrowserError("Browser has no CDP context.", "invalid_state");
+    }
+    const page = await context.newPage();
+    this.selected = page;
+    this.idFor(page);
+    return page;
+  }
+  selectTab(id) {
+    const page = this.pageFor(id);
+    this.selected = page;
+    return page;
+  }
+  async closeTab(id) {
+    const page = this.pageFor(id);
+    await page.close();
+    if (page === this.selected) this.selected = this.pages()[0];
+  }
+  idFor(page) {
+    const existing = this.tabIds.get(page);
+    if (existing !== void 0) return existing;
+    const id = randomUUID();
+    this.tabIds.set(page, id);
+    return id;
+  }
+  async disconnect() {
+    if (this.isClosed) return;
+    this.isClosed = true;
+    await this.browser.close().catch(() => void 0);
+  }
+  async [Symbol.asyncDispose]() {
+    await this.disconnect();
+  }
+  pages() {
+    return this.browser.contexts().flatMap((context) => context.pages());
+  }
+  pageFor(id) {
+    const page = this.pages().find((candidate) => this.idFor(candidate) === id);
+    if (page === void 0) {
+      throw new BrowserError(`Browser tab does not exist: ${id}`, "invalid_state");
+    }
+    return page;
+  }
+  assertOpen() {
+    if (this.closed) throw new BrowserError("Browser connection is closed.", "connection_closed");
+  }
+  async withAbort(abortSignal, operation) {
+    abortSignal?.throwIfAborted();
+    if (abortSignal === void 0) return operation();
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (callback) => {
+        if (settled) return;
+        settled = true;
+        abortSignal.removeEventListener("abort", onAbort);
+        callback();
+      };
+      const onAbort = () => {
+        void this.disconnect().finally(() => finish(() => reject(abortSignal.reason)));
+      };
+      abortSignal.addEventListener("abort", onAbort, { once: true });
+      void operation().then(
+        (value) => finish(() => resolve(value)),
+        (error) => finish(() => reject(error))
+      );
+    });
+  }
+};
+async function enforceNavigationPolicy(route, policy) {
+  const request = route.request();
+  const frame = request.frame();
+  if (request.isNavigationRequest() && frame === frame.page().mainFrame() && !isNavigationAllowed(request.url(), policy)) {
+    await route.abort("blockedbyclient");
+    return;
+  }
+  await route.continue();
+}
+function isNavigationAllowed(value, policy) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (url.username.length > 0 || url.password.length > 0) return false;
+  return policy.mode === "allow-all-http" || policy.origins.includes(url.origin);
+}
+function asConnection(connection) {
+  if (!(connection instanceof PlaywrightBrowserConnectionImpl)) {
+    throw new TypeError("connection must be created by DockerBrowser.connect().");
+  }
+  return connection;
+}
+
+// src/control.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var BrowserControlState = class {
+  activeAgentActions = 0;
+  pendingAcquire;
+  activeLease;
+  humanPending = false;
+  destroyed = false;
+  snapshot() {
+    const lease = this.activeLease;
+    return lease === void 0 ? Object.freeze({ mode: "agent" }) : Object.freeze({
+      mode: "human",
+      ownerId: lease.ownerId,
+      expiresAt: lease.expiresAt
+    });
+  }
+  async acquireHumanControl(options) {
+    validateAcquireOptions(options);
+    this.assertActive();
+    options.abortSignal?.throwIfAborted();
+    if (this.activeLease !== void 0 || this.humanPending) {
+      throw new BrowserError("Browser human control is already acquired.", "human_controlled");
+    }
+    this.humanPending = true;
+    try {
+      if (this.activeAgentActions > 0) {
+        await new Promise((resolve, reject) => {
+          const pending = { resolve, reject };
+          if (options.abortSignal !== void 0) {
+            pending.abortSignal = options.abortSignal;
+            pending.abort = () => {
+              if (this.pendingAcquire !== pending) return;
+              this.pendingAcquire = void 0;
+              reject(options.abortSignal?.reason);
+            };
+            options.abortSignal.addEventListener("abort", pending.abort, { once: true });
+          }
+          this.pendingAcquire = pending;
+        });
+      }
+      this.assertActive();
+      options.abortSignal?.throwIfAborted();
+      const lease = new BrowserHumanControlLeaseImpl({
+        owner: this,
+        ownerId: options.ownerId,
+        leaseTimeoutMs: options.leaseTimeoutMs
+      });
+      this.activeLease = lease;
+      return lease;
+    } finally {
+      this.humanPending = false;
+    }
+  }
+  async runAgentAction(operation) {
+    this.assertActive();
+    if (this.activeLease !== void 0 || this.humanPending) {
+      throw new BrowserError("Browser is controlled by a human viewer.", "human_controlled");
+    }
+    this.activeAgentActions += 1;
+    try {
+      return await operation();
+    } finally {
+      this.activeAgentActions -= 1;
+      if (this.activeAgentActions === 0) this.resolvePendingAcquire();
+    }
+  }
+  renewLease(lease, options) {
+    if (this.activeLease !== lease) {
+      throw new BrowserError("Browser human control lease is no longer active.", "invalid_state");
+    }
+    assertPositiveSafeInteger(options.leaseTimeoutMs, "leaseTimeoutMs");
+    lease.resetExpiration(options.leaseTimeoutMs);
+    return this.snapshot();
+  }
+  releaseLease(lease) {
+    if (this.activeLease !== lease) return;
+    this.activeLease = void 0;
+    lease.markReleased();
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.activeLease?.release();
+    if (this.pendingAcquire !== void 0) {
+      const pending = this.pendingAcquire;
+      this.pendingAcquire = void 0;
+      if (pending.abort !== void 0) {
+        pending.abortSignal?.removeEventListener("abort", pending.abort);
+      }
+      pending.reject(new BrowserError("Browser was destroyed.", "invalid_state"));
+    }
+  }
+  assertActive() {
+    if (this.destroyed) throw new BrowserError("Browser was destroyed.", "invalid_state");
+  }
+  resolvePendingAcquire() {
+    const pending = this.pendingAcquire;
+    if (pending === void 0) return;
+    this.pendingAcquire = void 0;
+    if (pending.abort !== void 0) {
+      pending.abortSignal?.removeEventListener("abort", pending.abort);
+    }
+    pending.resolve();
+  }
+};
+var BrowserHumanControlLeaseImpl = class {
+  id = randomUUID2();
+  ownerId;
+  owner;
+  expiration = 0;
+  timer;
+  released = false;
+  constructor(options) {
+    this.owner = options.owner;
+    this.ownerId = options.ownerId;
+    this.resetExpiration(options.leaseTimeoutMs);
+  }
+  get expiresAt() {
+    return new Date(this.expiration).toISOString();
+  }
+  renew(options) {
+    if (this.released) {
+      throw new BrowserError("Browser human control lease is no longer active.", "invalid_state");
+    }
+    return this.owner.renewLease(this, options);
+  }
+  release() {
+    this.owner.releaseLease(this);
+  }
+  markReleased() {
+    if (this.released) return;
+    this.released = true;
+    if (this.timer !== void 0) clearTimeout(this.timer);
+    this.timer = void 0;
+  }
+  resetExpiration(leaseTimeoutMs) {
+    if (this.timer !== void 0) clearTimeout(this.timer);
+    this.expiration = Date.now() + leaseTimeoutMs;
+    this.timer = setTimeout(() => this.release(), leaseTimeoutMs);
+    this.timer.unref?.();
+  }
+  async [Symbol.asyncDispose]() {
+    this.release();
+  }
+};
+function validateAcquireOptions(options) {
+  if (!isRecord(options)) throw new TypeError("options must be an object.");
+  if (typeof options.ownerId !== "string" || options.ownerId.length === 0) {
+    throw new TypeError("ownerId must be a non-empty string.");
+  }
+  assertPositiveSafeInteger(options.leaseTimeoutMs, "leaseTimeoutMs");
+}
+function assertPositiveSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(`${name} must be a positive safe integer.`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/docker-browser.ts
+var cdpPort = 9222;
+var noVncPort = 6080;
+var browserSchema = "1";
+var defaultSharedMemoryMb = 1024;
+var seccompProfilePath = fileURLToPath(
+  new URL("../security/seccomp_profile.json", import.meta.url)
+);
+var DockerBrowserClient = class {
+  sandboxClient;
+  image;
+  constructor(options) {
+    if (!isRecord2(options)) throw new TypeError("options must be an object.");
+    if (!isSandboxClient(options.sandboxClient)) {
+      throw new TypeError("sandboxClient must be a DockerSandboxClient.");
+    }
+    assertNonEmptyString(options.image, "image");
+    this.sandboxClient = options.sandboxClient;
+    this.image = options.image;
+  }
+  async pullImage(options = {}) {
+    assertOptionsObject(options);
+    let pullOptions = { image: this.image };
+    if (options.abortSignal !== void 0) {
+      pullOptions = { ...pullOptions, abortSignal: options.abortSignal };
+    }
+    await this.sandboxClient.pullImage(pullOptions);
+  }
+  async createBrowser(options) {
+    validateCreateOptions(options);
+    options.abortSignal?.throwIfAborted();
+    const resources = {
+      ...options.resources,
+      sharedMemoryMb: options.resources?.sharedMemoryMb ?? defaultSharedMemoryMb
+    };
+    let sandboxOptions = {
+      image: this.image,
+      workdir: "/workspace",
+      workspace: options.workspace,
+      network: { mode: "bridge", ports: [cdpPort, noVncPort] },
+      user: "pwuser",
+      labels: {
+        "anvia.browser.schema": browserSchema
+      },
+      resources,
+      security: {
+        noNewPrivileges: true,
+        dropCapabilities: ["ALL"],
+        addCapabilities: ["SYS_CHROOT"],
+        seccompProfile: { type: "path", path: seccompProfilePath }
+      }
+    };
+    if (options.id !== void 0) sandboxOptions = { ...sandboxOptions, id: options.id };
+    if (options.runtime !== void 0) {
+      sandboxOptions = { ...sandboxOptions, runtime: options.runtime };
+    }
+    if (options.abortSignal !== void 0) {
+      sandboxOptions = { ...sandboxOptions, abortSignal: options.abortSignal };
+    }
+    const sandbox = await this.sandboxClient.createSandbox(sandboxOptions);
+    try {
+      await configureBrowser(sandbox, options);
+      await startBrowserServices(sandbox, options.abortSignal);
+      return new DockerBrowserHandle(sandbox);
+    } catch (error) {
+      await sandbox.destroy().catch(() => void 0);
+      throw new BrowserError("Unable to configure the browser sandbox.", "startup_failed", {
+        cause: error
+      });
+    }
+  }
+  async resumeBrowser(options) {
+    assertOptionsObject(options);
+    assertNonEmptyString(options.id, "id");
+    options.abortSignal?.throwIfAborted();
+    const sandbox = await this.sandboxClient.resumeSandbox(options);
+    try {
+      await assertBrowserImage(sandbox, options.abortSignal);
+      await startBrowserServices(sandbox, options.abortSignal);
+      return new DockerBrowserHandle(sandbox);
+    } catch (error) {
+      await sandbox.stop().catch(() => void 0);
+      throw new BrowserError("Unable to resume browser services.", "startup_failed", {
+        cause: error
+      });
+    }
+  }
+};
+var DockerBrowserHandle = class {
+  id;
+  sandbox;
+  desktop;
+  control = new BrowserControlState();
+  connections = /* @__PURE__ */ new Set();
+  constructor(sandbox) {
+    this.sandbox = sandbox;
+    this.id = sandbox.id;
+    this.desktop = Object.freeze({
+      protocol: "novnc",
+      containerPort: noVncPort,
+      control: this.control
+    });
+  }
+  get state() {
+    return this.sandbox.state;
+  }
+  inspector(options) {
+    return this.sandbox.inspector(options);
+  }
+  async waitUntilReady(options) {
+    assertOptionsObject(options);
+    assertPositiveSafeInteger2(options.timeoutMs, "timeoutMs");
+    this.assertRunning();
+    const timeout = AbortSignal.timeout(options.timeoutMs);
+    const abortSignal = options.abortSignal === void 0 ? timeout : AbortSignal.any([options.abortSignal, timeout]);
+    try {
+      await Promise.all([
+        this.sandbox.runtime.waitForPort({
+          containerPort: cdpPort,
+          timeoutMs: options.timeoutMs,
+          abortSignal
+        }),
+        this.sandbox.runtime.waitForPort({
+          containerPort: noVncPort,
+          timeoutMs: options.timeoutMs,
+          abortSignal
+        })
+      ]);
+      await Promise.all([
+        assertHttpReady(`${endpointFor(this.sandbox, cdpPort)}/json/version`, abortSignal),
+        assertHttpReady(`${endpointFor(this.sandbox, noVncPort)}/vnc.html`, abortSignal)
+      ]);
+    } catch (error) {
+      if (options.abortSignal?.aborted) options.abortSignal.throwIfAborted();
+      throw new BrowserError("Browser did not become ready before the timeout.", "not_ready", {
+        cause: error
+      });
+    }
+  }
+  async connect(options = {}) {
+    assertOptionsObject(options);
+    this.assertRunning();
+    try {
+      let connectOptions = {
+        endpointUrl: endpointFor(this.sandbox, cdpPort),
+        control: this.control
+      };
+      if (options.abortSignal !== void 0) {
+        connectOptions = { ...connectOptions, abortSignal: options.abortSignal };
+      }
+      const connection = await connectPlaywrightBrowser(connectOptions);
+      this.connections.add(connection);
+      return connection;
+    } catch (error) {
+      if (options.abortSignal?.aborted) options.abortSignal.throwIfAborted();
+      throw new BrowserError("Unable to connect to Chromium over CDP.", "not_ready", {
+        cause: error
+      });
+    }
+  }
+  async stop(options = {}) {
+    assertOptionsObject(options);
+    await this.disconnectAll();
+    await this.sandbox.stop(options);
+  }
+  async destroy() {
+    this.control.destroy();
+    await this.disconnectAll();
+    await this.sandbox.destroy();
+  }
+  async [Symbol.asyncDispose]() {
+    await this.destroy();
+  }
+  assertRunning() {
+    if (this.state !== "running") {
+      throw new BrowserError(`Browser is not running: ${this.state}`, "invalid_state");
+    }
+  }
+  async disconnectAll() {
+    const connections = [...this.connections];
+    this.connections.clear();
+    const results = await Promise.allSettled(
+      connections.map((connection) => connection.disconnect())
+    );
+    const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+    if (failures.length > 0) {
+      throw new AggregateError(failures, "Unable to disconnect browser automation clients.");
+    }
+  }
+};
+async function configureBrowser(sandbox, options) {
+  let execOptions = {
+    command: "/usr/local/bin/anvia-browser-configure",
+    input: JSON.stringify({
+      password: options.desktop.password,
+      width: options.desktop.viewport.width,
+      height: options.desktop.viewport.height
+    })
+  };
+  if (options.abortSignal !== void 0) {
+    execOptions = { ...execOptions, abortSignal: options.abortSignal };
+  }
+  const result = await sandbox.runtime.exec(execOptions);
+  if (result.status !== "exited" || result.exitCode !== 0) {
+    throw new Error("Browser image rejected its runtime configuration.");
+  }
+}
+async function assertBrowserImage(sandbox, abortSignal) {
+  let execOptions = {
+    command: "/usr/local/bin/anvia-browser-version"
+  };
+  if (abortSignal !== void 0) execOptions = { ...execOptions, abortSignal };
+  const result = await sandbox.runtime.exec(execOptions);
+  if (result.status !== "exited" || result.exitCode !== 0 || new TextDecoder("utf-8", { fatal: true }).decode(result.stdout).trim() !== browserSchema) {
+    throw new Error("Sandbox does not contain a compatible Anvia browser image.");
+  }
+}
+async function startBrowserServices(sandbox, abortSignal) {
+  let startOptions = {
+    command: "/usr/local/bin/anvia-browser-start"
+  };
+  if (abortSignal !== void 0) startOptions = { ...startOptions, abortSignal };
+  await sandbox.runtime.startProcess(startOptions);
+}
+async function assertHttpReady(url, abortSignal) {
+  while (true) {
+    abortSignal.throwIfAborted();
+    try {
+      const response = await fetch(url, { signal: abortSignal, redirect: "error" });
+      if (response.ok) {
+        await response.body?.cancel();
+        return;
+      }
+      await response.body?.cancel();
+    } catch (error) {
+      if (abortSignal.aborted) throw abortSignal.reason ?? error;
+    }
+    await waitForRetry(abortSignal);
+  }
+}
+async function waitForRetry(abortSignal) {
+  await new Promise((resolve, reject) => {
+    const timeout = setTimeout(finish, 50);
+    const abort = () => finish(abortSignal.reason ?? new DOMException("Aborted", "AbortError"));
+    abortSignal.addEventListener("abort", abort, { once: true });
+    function finish(error) {
+      clearTimeout(timeout);
+      abortSignal.removeEventListener("abort", abort);
+      if (error === void 0) resolve();
+      else reject(error);
+    }
+  });
+}
+function endpointFor(sandbox, containerPort) {
+  const published = publishedPort(sandbox, containerPort);
+  return `http://${hostForUrl(published.host)}:${published.hostPort}`;
+}
+function publishedPort(sandbox, containerPort) {
+  const port = sandbox.runtime.publishedPorts.find(
+    (candidate) => candidate.containerPort === containerPort && candidate.protocol === "tcp"
+  );
+  if (port === void 0) {
+    throw new BrowserError(`Browser port is not published: ${containerPort}`, "invalid_state");
+  }
+  return port;
+}
+function hostForUrl(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}
+function validateCreateOptions(options) {
+  assertOptionsObject(options);
+  if (options.id !== void 0) assertNonEmptyString(options.id, "id");
+  if (!isRecord2(options.workspace)) throw new TypeError("workspace must be an object.");
+  if (!isRecord2(options.network) || options.network.mode !== "bridge") {
+    throw new TypeError('network must be { mode: "bridge" }.');
+  }
+  if (!isRecord2(options.desktop) || options.desktop.protocol !== "novnc") {
+    throw new TypeError('desktop must use protocol: "novnc".');
+  }
+  if (!/^[\x20-\x7e]{8}$/.test(options.desktop.password)) {
+    throw new TypeError("desktop.password must contain exactly 8 printable ASCII characters.");
+  }
+  if (!isRecord2(options.desktop.viewport)) {
+    throw new TypeError("desktop.viewport must be an object.");
+  }
+  assertIntegerInRange(options.desktop.viewport.width, "desktop.viewport.width", 640, 3840);
+  assertIntegerInRange(options.desktop.viewport.height, "desktop.viewport.height", 480, 2160);
+  if (options.runtime?.maxProcesses !== void 0 && options.runtime.maxProcesses < 1) {
+    throw new RangeError("runtime.maxProcesses must allow the browser service process.");
+  }
+}
+function assertIntegerInRange(value, name, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be a safe integer between ${min} and ${max}.`);
+  }
+}
+function assertPositiveSafeInteger2(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(`${name} must be a positive safe integer.`);
+  }
+}
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string.`);
+  }
+}
+function assertOptionsObject(value) {
+  if (!isRecord2(value)) throw new TypeError("options must be an object.");
+}
+function isSandboxClient(value) {
+  return isRecord2(value) && typeof value.pullImage === "function" && typeof value.createSandbox === "function" && typeof value.resumeSandbox === "function";
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/tools.ts
+import { createTool, ToolOutput } from "@anvia/core/tool";
+import { z } from "zod";
+var targetSchema = z.discriminatedUnion("by", [
+  z.object({
+    by: z.literal("role"),
+    role: z.string().min(1),
+    name: z.string().optional(),
+    exact: z.boolean().optional()
+  }),
+  z.object({ by: z.literal("text"), text: z.string().min(1), exact: z.boolean().optional() }),
+  z.object({ by: z.literal("label"), label: z.string().min(1), exact: z.boolean().optional() }),
+  z.object({
+    by: z.literal("placeholder"),
+    placeholder: z.string().min(1),
+    exact: z.boolean().optional()
+  }),
+  z.object({ by: z.literal("test-id"), testId: z.string().min(1) }),
+  z.object({ by: z.literal("css"), selector: z.string().min(1) })
+]);
+var noInput = z.object({});
+var tabInput = z.object({ tabId: z.string().uuid() });
+var navigateInput = z.object({
+  url: z.url(),
+  waitUntil: z.enum(["commit", "domcontentloaded", "load", "networkidle"]).optional()
+});
+var clickInput = z.object({ target: targetSchema });
+var typeInput = z.object({ target: targetSchema, text: z.string() });
+var pressKeyInput = z.object({ key: z.string().min(1).max(100) });
+var screenshotInput = z.object({});
+var defaultActionTimeoutMs = 1e4;
+var defaultNavigationTimeoutMs = 3e4;
+var defaultSnapshotMaxChars = 5e4;
+var maxTimeoutMs = 3e5;
+var maxSnapshotChars = 2e5;
+function createBrowserTools(options) {
+  validateFactoryOptions(options);
+  const connection = asConnection(options.connection);
+  const policy = snapshotNavigationPolicy(options.navigation);
+  connection.setNavigationPolicy(policy);
+  const limits = {
+    actionTimeoutMs: options.limits?.actionTimeoutMs ?? defaultActionTimeoutMs,
+    navigationTimeoutMs: options.limits?.navigationTimeoutMs ?? defaultNavigationTimeoutMs,
+    snapshotMaxChars: options.limits?.snapshotMaxChars ?? defaultSnapshotMaxChars
+  };
+  const tools = options.tools.map((name) => {
+    switch (name) {
+      case "browser_list_tabs":
+        return createListTabsTool(connection);
+      case "browser_open_tab":
+        return createOpenTabTool(connection);
+      case "browser_select_tab":
+        return createSelectTabTool(connection);
+      case "browser_close_tab":
+        return createCloseTabTool(connection);
+      case "browser_navigate":
+        return createNavigateTool(connection, policy, limits.navigationTimeoutMs);
+      case "browser_snapshot":
+        return createSnapshotTool(connection, limits.actionTimeoutMs, limits.snapshotMaxChars);
+      case "browser_click":
+        return createClickTool(connection, limits.actionTimeoutMs);
+      case "browser_type":
+        return createTypeTool(connection, limits.actionTimeoutMs);
+      case "browser_press_key":
+        return createPressKeyTool(connection);
+      case "browser_screenshot":
+        return createScreenshotTool(connection);
+      default:
+        return assertNever(name);
+    }
+  });
+  return Object.freeze(tools);
+}
+function createListTabsTool(connection) {
+  return createTool({
+    name: "browser_list_tabs",
+    description: "List Chromium tabs and identify the tab selected for subsequent browser tools.",
+    inputSchema: noInput,
+    execute: async () => ({ tabs: await connection.listTabs() })
+  });
+}
+function createOpenTabTool(connection) {
+  return createTool({
+    name: "browser_open_tab",
+    description: "Open and select a new blank Chromium tab.",
+    inputSchema: noInput,
+    execute: async (_args, context) => connection.runAction(context.abortSignal, async () => {
+      const page = await connection.openTab();
+      return tabResult(connection, page);
+    })
+  });
+}
+function createSelectTabTool(connection) {
+  return createTool({
+    name: "browser_select_tab",
+    description: "Select an existing Chromium tab by its browser tab ID.",
+    inputSchema: tabInput,
+    execute: async ({ tabId }, context) => connection.runAction(
+      context.abortSignal,
+      async () => tabResult(connection, connection.selectTab(tabId))
+    )
+  });
+}
+function createCloseTabTool(connection) {
+  return createTool({
+    name: "browser_close_tab",
+    description: "Close an existing Chromium tab by its browser tab ID.",
+    inputSchema: tabInput,
+    execute: async ({ tabId }, context) => connection.runAction(context.abortSignal, async () => {
+      await connection.closeTab(tabId);
+      return { closedTabId: tabId, tabs: await connection.tabSummaries() };
+    })
+  });
+}
+function createNavigateTool(connection, policy, timeoutMs) {
+  return createTool({
+    name: "browser_navigate",
+    description: "Navigate the selected Chromium tab to an allowed HTTP or HTTPS URL.",
+    inputSchema: navigateInput,
+    execute: async ({ url, waitUntil }, context) => connection.runAction(context.abortSignal, async () => {
+      assertNavigationAllowed(url, policy);
+      const page = connection.selectedPage();
+      await page.goto(url, {
+        timeout: timeoutMs,
+        waitUntil: waitUntil ?? "load"
+      });
+      assertNavigationAllowed(page.url(), policy);
+      return tabResult(connection, page);
+    })
+  });
+}
+function createSnapshotTool(connection, timeoutMs, maxChars) {
+  return createTool({
+    name: "browser_snapshot",
+    description: "Inspect the selected tab using a bounded ARIA accessibility snapshot.",
+    inputSchema: noInput,
+    execute: async (_args, context) => connection.runAction(context.abortSignal, async () => {
+      const page = connection.selectedPage();
+      const snapshot = await page.locator("body").ariaSnapshot({ timeout: timeoutMs });
+      const truncated = snapshot.length > maxChars;
+      return {
+        ...await tabResult(connection, page),
+        snapshot: truncated ? snapshot.slice(0, maxChars) : snapshot,
+        truncated
+      };
+    })
+  });
+}
+function createClickTool(connection, timeoutMs) {
+  return createTool({
+    name: "browser_click",
+    description: "Click one strictly matched element in the selected tab.",
+    inputSchema: clickInput,
+    execute: async ({ target }, context) => connection.runAction(context.abortSignal, async () => {
+      const page = connection.selectedPage();
+      await locatorFor(page, target).click({ timeout: timeoutMs });
+      return tabResult(connection, page);
+    })
+  });
+}
+function createTypeTool(connection, timeoutMs) {
+  return createTool({
+    name: "browser_type",
+    description: "Replace the value of one strictly matched editable element.",
+    inputSchema: typeInput,
+    execute: async ({ target, text }, context) => connection.runAction(context.abortSignal, async () => {
+      const page = connection.selectedPage();
+      await locatorFor(page, target).fill(text, { timeout: timeoutMs });
+      return tabResult(connection, page);
+    })
+  });
+}
+function createPressKeyTool(connection) {
+  return createTool({
+    name: "browser_press_key",
+    description: "Press an explicit keyboard key or key combination in the selected tab.",
+    inputSchema: pressKeyInput,
+    execute: async ({ key }, context) => connection.runAction(context.abortSignal, async () => {
+      const page = connection.selectedPage();
+      await page.keyboard.press(key);
+      return tabResult(connection, page);
+    })
+  });
+}
+function createScreenshotTool(connection) {
+  return createTool({
+    name: "browser_screenshot",
+    description: "Capture the visible viewport of the selected Chromium tab as PNG.",
+    inputSchema: screenshotInput,
+    execute: async (_args, context) => connection.runAction(context.abortSignal, async () => {
+      const page = connection.selectedPage();
+      const png = await page.screenshot({ type: "png", fullPage: false });
+      const metadata = await tabResult(connection, page);
+      return ToolOutput.content([
+        { type: "text", text: JSON.stringify(metadata) },
+        {
+          type: "file",
+          data: { type: "data", data: png.toString("base64") },
+          mediaType: "image/png",
+          filename: "browser-screenshot.png"
+        }
+      ]);
+    })
+  });
+}
+async function tabResult(connection, page) {
+  return {
+    tabId: connection.idFor(page),
+    title: await page.title(),
+    url: page.url()
+  };
+}
+function locatorFor(page, target) {
+  switch (target.by) {
+    case "role": {
+      const options = {};
+      if (target.name !== void 0) options.name = target.name;
+      if (target.exact !== void 0) options.exact = target.exact;
+      return page.getByRole(target.role, options);
+    }
+    case "text": {
+      const options = {};
+      if (target.exact !== void 0) options.exact = target.exact;
+      return page.getByText(target.text, options);
+    }
+    case "label": {
+      const options = {};
+      if (target.exact !== void 0) options.exact = target.exact;
+      return page.getByLabel(target.label, options);
+    }
+    case "placeholder": {
+      const options = {};
+      if (target.exact !== void 0) options.exact = target.exact;
+      return page.getByPlaceholder(target.placeholder, options);
+    }
+    case "test-id":
+      return page.getByTestId(target.testId);
+    case "css":
+      return page.locator(target.selector);
+  }
+}
+function snapshotNavigationPolicy(policy) {
+  if (!isRecord3(policy)) throw new TypeError("navigation must be an object.");
+  if (policy.mode === "allow-all-http") return Object.freeze({ mode: "allow-all-http" });
+  if (policy.mode !== "origins" || !Array.isArray(policy.origins) || policy.origins.length === 0) {
+    throw new TypeError(
+      "navigation must explicitly allow all HTTP URLs or a non-empty origin list."
+    );
+  }
+  const origins = policy.origins.map((origin) => normalizeOrigin(origin));
+  if (new Set(origins).size !== origins.length) {
+    throw new TypeError("navigation.origins contains a duplicate origin.");
+  }
+  return Object.freeze({ mode: "origins", origins: Object.freeze(origins) });
+}
+function normalizeOrigin(value) {
+  if (typeof value !== "string") throw new TypeError("navigation origin must be a string.");
+  const url = parseHttpUrl(value);
+  if (value !== url.origin) {
+    throw new TypeError(`navigation origin must not contain a path, query, or fragment: ${value}`);
+  }
+  return url.origin;
+}
+function assertNavigationAllowed(value, policy) {
+  if (!isNavigationAllowed2(value, policy)) {
+    throw new BrowserError(`Browser navigation is blocked: ${value}`, "navigation_blocked");
+  }
+}
+function isNavigationAllowed2(value, policy) {
+  let url;
+  try {
+    url = parseHttpUrl(value);
+  } catch {
+    return false;
+  }
+  return policy.mode === "allow-all-http" || policy.origins.includes(url.origin);
+}
+function parseHttpUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new TypeError("Browser navigation only supports HTTP and HTTPS URLs.");
+  }
+  if (url.username.length > 0 || url.password.length > 0) {
+    throw new TypeError("Browser navigation URLs must not include credentials.");
+  }
+  return url;
+}
+function validateFactoryOptions(options) {
+  if (!isRecord3(options)) throw new TypeError("options must be an object.");
+  if (!Array.isArray(options.tools) || options.tools.length === 0) {
+    throw new TypeError("tools must be a non-empty array.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of options.tools) {
+    if (!isToolName(name)) throw new TypeError(`Unsupported browser tool name: ${name}`);
+    if (seen.has(name)) throw new TypeError(`tools contains a duplicate: ${name}`);
+    seen.add(name);
+  }
+  snapshotNavigationPolicy(options.navigation);
+  if (options.limits !== void 0 && !isRecord3(options.limits)) {
+    throw new TypeError("limits must be an object.");
+  }
+  assertOptionalBoundedInteger(options.limits?.actionTimeoutMs, "actionTimeoutMs", 1, maxTimeoutMs);
+  assertOptionalBoundedInteger(
+    options.limits?.navigationTimeoutMs,
+    "navigationTimeoutMs",
+    1,
+    maxTimeoutMs
+  );
+  assertOptionalBoundedInteger(
+    options.limits?.snapshotMaxChars,
+    "snapshotMaxChars",
+    1,
+    maxSnapshotChars
+  );
+}
+function assertOptionalBoundedInteger(value, name, min, max) {
+  if (value !== void 0 && (!Number.isSafeInteger(value) || value < min || value > max)) {
+    throw new RangeError(`${name} must be a safe integer between ${min} and ${max}.`);
+  }
+}
+function isToolName(value) {
+  return typeof value === "string" && [
+    "browser_list_tabs",
+    "browser_open_tab",
+    "browser_select_tab",
+    "browser_close_tab",
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_click",
+    "browser_type",
+    "browser_press_key",
+    "browser_screenshot"
+  ].includes(value);
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertNever(value) {
+  throw new TypeError(`Unsupported browser tool: ${value}`);
+}
+export {
+  BrowserError,
+  DockerBrowserClient,
+  createBrowserTools
+};
+//# sourceMappingURL=index.js.map