@eidentic/browser 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Baran Özdemir
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,104 @@
+# @eidentic/browser
+
+Sealed browser-automation tools for Eidentic — first-class sandboxed browser tools over an
+injected `PageLike` page. Pass any object that satisfies the `PageLike` interface: a real
+Playwright `Page`, or a faithful in-memory fake for tests.
+
+## Install
+
+```bash
+pnpm add @eidentic/browser playwright-core
+npx playwright install chromium
+```
+
+## Usage
+
+```ts
+import { chromium } from "playwright-core";
+import { browserTools } from "@eidentic/browser";
+import { Agent } from "eidentic";
+
+const browser = await chromium.launch({ headless: true });
+const context = await browser.newContext();
+const page = await context.newPage();
+
+const agent = new Agent({
+  id: "web-agent",
+  model,
+  store,
+  tools: browserTools(page, {
+    allowlist: ["example.com", "docs.example.com"],
+  }),
+});
+
+for await (const ev of agent.query("What is on the homepage of example.com?", { sessionId: "s-1" })) {
+  if (ev.kind === "text_delta") process.stdout.write(ev.delta);
+}
+
+await browser.close();
+```
+
+## Tools
+
+| Tool ID | Side effect | Description |
+|---|---|---|
+| `browser_navigate` | `destructive` | Navigate to an `http(s)` URL. Validates before AND after navigation (redirect escape detection). |
+| `browser_read` | `read-only` | Read current page title, URL, and text (body or a CSS selector). Truncated to `maxContentBytes`. |
+| `browser_click` | `destructive` | Click an element by CSS selector. Errors are tool errors, not throws. |
+| `browser_fill` | `destructive` | Fill an input by CSS selector. Errors are tool errors, not throws. |
+
+## Security
+
+Every `browser_navigate` call:
+1. Validates the target URL scheme (`http`/`https` only).
+2. Checks the host against the private-IP/loopback/metadata blocklist (SSRF defense, mirrors `@eidentic/tools`).
+3. Checks the host against your `allowlist` (when configured).
+4. After `goto()`, **re-validates `page.url()`** — so server-side redirects that would escape the
+   allowlist or land on a private host are caught and returned as tool errors before the agent can act on them.
+
+## Options
+
+```ts
+browserTools(page, {
+  // Optional: restrict navigation to these hostnames (and their subdomains).
+  // Omit for no restriction; pass [] to deny all navigation.
+  allowlist?: string[];
+
+  // Default: true. Set to false only in controlled test environments.
+  blockPrivateHosts?: boolean;
+
+  // Max UTF-8 bytes in browser_read results. Default: 512 KB.
+  maxContentBytes?: number;
+})
+```
+
+## PageLike interface
+
+```ts
+interface PageLike {
+  goto(url: string): Promise<unknown>;
+  content(): Promise<string>;
+  innerText(selector: string): Promise<string>;
+  click(selector: string): Promise<void>;
+  fill(selector: string, value: string): Promise<void>;
+  url(): string;
+  title(): Promise<string>;
+  screenshot?(): Promise<Uint8Array>; // optional, not exposed as a tool in v1
+}
+```
+
+A real `playwright-core` `Page` satisfies this interface structurally. No adapter needed.
+
+## Roadmap
+
+- `browser_screenshot`: returns a base64-encoded screenshot string. Not in v1 because binary results
+  don't compose cleanly with text tool results; the encoding overhead and context-window cost warrant
+  a dedicated design.
+
+## Links
+
+- [GitHub](https://github.com/eidentic/eidentic)
+- [Issue tracker](https://github.com/eidentic/eidentic/issues)
+- [Root README](https://github.com/eidentic/eidentic#readme)
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,158 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  browserTools: () => browserTools,
+  hostAllowed: () => import_tools2.hostAllowed,
+  isBlockedHost: () => import_tools2.isBlockedHost
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("zod");
+var import_core = require("@eidentic/core");
+var import_tools = require("@eidentic/tools");
+var import_tools2 = require("@eidentic/tools");
+var DEFAULT_MAX_CONTENT_BYTES = 512 * 1024;
+var TRUNCATION_MARKER = "\n\u2026[content truncated]";
+function assertNavigableUrl(rawUrl, opts) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error(`browser: invalid URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`browser: only http(s) URLs are allowed (got ${parsed.protocol})`);
+  }
+  if (opts.blockPrivateHosts && (0, import_tools.isBlockedHost)(parsed.hostname)) {
+    throw new Error(
+      `browser: host is a blocked private/loopback/metadata address: ${parsed.hostname}`
+    );
+  }
+  if (opts.allowlist !== void 0 && !(0, import_tools.hostAllowed)(parsed.hostname, opts.allowlist)) {
+    throw new Error(
+      `browser: host not on allowlist: ${parsed.hostname}`
+    );
+  }
+  return parsed;
+}
+function truncateContent(text, maxBytes) {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= maxBytes) return text;
+  const markerBuf = Buffer.from(TRUNCATION_MARKER, "utf8");
+  const cutBytes = maxBytes - markerBuf.length;
+  return buf.subarray(0, cutBytes > 0 ? cutBytes : 0).toString("utf8") + TRUNCATION_MARKER;
+}
+function browserTools(page, opts) {
+  const blockPrivateHosts = opts?.blockPrivateHosts ?? true;
+  const maxContentBytes = opts?.maxContentBytes ?? DEFAULT_MAX_CONTENT_BYTES;
+  const guardOpts = { allowlist: opts?.allowlist, blockPrivateHosts };
+  const navigateTool = (0, import_core.createTool)({
+    id: "browser_navigate",
+    description: "Navigate the browser page to an http(s) URL. Only http(s) schemes are accepted. Private/loopback/metadata hosts are always rejected (SSRF defense). When an egress allowlist is configured, the host must be on it. After navigation, the final URL is re-validated to detect redirect-based escapes \u2014 the tool errors if the page was redirected off the allowlist.",
+    inputSchema: import_zod.z.object({
+      url: import_zod.z.string().describe("Absolute http(s) URL to navigate to")
+    }),
+    sideEffect: "destructive",
+    execute: async ({ input }) => {
+      assertNavigableUrl(input.url, guardOpts);
+      try {
+        await page.goto(input.url);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`browser_navigate: goto failed: ${msg}`);
+      }
+      const finalUrl = page.url();
+      try {
+        assertNavigableUrl(finalUrl, guardOpts);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `browser_navigate: redirect to blocked/disallowed URL detected after navigation: ${msg}`
+        );
+      }
+      return { navigated: true, url: finalUrl };
+    }
+  });
+  const readTool = (0, import_core.createTool)({
+    id: "browser_read",
+    description: "Read the current page's title, URL, and text content. When `selector` is provided, returns innerText of that element; otherwise returns innerText of the `body` element. Content is truncated to the configured `maxContentBytes` limit.",
+    inputSchema: import_zod.z.object({
+      selector: import_zod.z.string().optional().describe("CSS selector to read (defaults to `body` if omitted)")
+    }),
+    sideEffect: "read-only",
+    execute: async ({ input }) => {
+      const title = await page.title();
+      const url = page.url();
+      const sel = input.selector ?? "body";
+      let text;
+      try {
+        text = await page.innerText(sel);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `browser_read: innerText failed for selector "${sel}": ${msg}`, title, url };
+      }
+      const truncated = truncateContent(text, maxContentBytes);
+      return { title, url, text: truncated, truncated: truncated !== text };
+    }
+  });
+  const clickTool = (0, import_core.createTool)({
+    id: "browser_click",
+    description: "Click an element on the current page identified by a CSS selector. Selector errors (element not found, ambiguous) are surfaced as tool errors, not throws.",
+    inputSchema: import_zod.z.object({
+      selector: import_zod.z.string().describe("CSS selector of the element to click")
+    }),
+    sideEffect: "destructive",
+    execute: async ({ input }) => {
+      try {
+        await page.click(input.selector);
+        return { clicked: true, selector: input.selector };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `browser_click: click failed for selector "${input.selector}": ${msg}`, clicked: false };
+      }
+    }
+  });
+  const fillTool = (0, import_core.createTool)({
+    id: "browser_fill",
+    description: "Fill an input, textarea, or contenteditable element on the current page identified by a CSS selector. Selector errors are surfaced as tool errors, not throws.",
+    inputSchema: import_zod.z.object({
+      selector: import_zod.z.string().describe("CSS selector of the input element to fill"),
+      value: import_zod.z.string().describe("Value to fill into the element")
+    }),
+    sideEffect: "destructive",
+    execute: async ({ input }) => {
+      try {
+        await page.fill(input.selector, input.value);
+        return { filled: true, selector: input.selector };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `browser_fill: fill failed for selector "${input.selector}": ${msg}`, filled: false };
+      }
+    }
+  });
+  return [navigateTool, readTool, clickTool, fillTool];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  browserTools,
+  hostAllowed,
+  isBlockedHost
+});

package/dist/index.d.cts

@@ -0,0 +1,98 @@
+import { Tool } from '@eidentic/core';
+export { hostAllowed, isBlockedHost } from '@eidentic/tools';
+
+/**
+ * Minimal structural interface for a browser page that `browserTools` can operate on.
+ *
+ * Designed as a strict subset of Playwright's `Page` type — a real `playwright-core`
+ * `Page` instance satisfies this interface without any adapter. You can also pass a
+ * faithful in-memory fake for tests (see `FakePage` in the test suite).
+ *
+ * `screenshot` is intentionally optional: it is NOT surfaced as a tool in v1 (binary
+ * results don't compose cleanly with text tool results). Roadmap: a future `browser_screenshot`
+ * tool returning a base64-encoded image string.
+ */
+interface PageLike {
+    /** Navigate to `url`. Returns when navigation is complete. */
+    goto(url: string): Promise<unknown>;
+    /** Return the full HTML content of the current page. */
+    content(): Promise<string>;
+    /** Return the innerText of the element matching `selector`. Throws if not found. */
+    innerText(selector: string): Promise<string>;
+    /** Click the element matching `selector`. */
+    click(selector: string): Promise<void>;
+    /** Fill an input element matching `selector` with `value`. */
+    fill(selector: string, value: string): Promise<void>;
+    /** Return the current page URL string. */
+    url(): string;
+    /** Return the page title. */
+    title(): Promise<string>;
+    /** Optional: capture a screenshot as raw bytes (not exposed as a tool in v1). Roadmap item. */
+    screenshot?(): Promise<Uint8Array>;
+}
+interface BrowserToolsOptions {
+    /**
+     * Egress allowlist of hostnames for browser navigation (§5.6 / §10.3). A host is allowed when
+     * it equals an entry OR is a subdomain of an entry (suffix match on a dot boundary).
+     *
+     * - **Omitted (`undefined`):** no domain restriction — any public http(s) host may be navigated to.
+     * - **Empty array (`[]`):** denies ALL navigation (explicit lockdown).
+     * - **Non-empty:** restricts navigation to the listed hosts (and their subdomains).
+     *
+     * In every mode, private / loopback / link-local / cloud-metadata hosts are ALWAYS rejected
+     * (SSRF defense, see `isBlockedHost` from `@eidentic/tools`).
+     *
+     * Every navigation, including model-driven `browser_navigate` calls, is re-validated:
+     * the tool validates the target URL before `goto()`, and then re-validates the URL reported
+     * by `page.url()` AFTER navigation completes — so redirect-based escapes are detected and
+     * surfaced as tool errors.
+     */
+    allowlist?: string[];
+    /**
+     * When true (default), private/loopback/link-local/cloud-metadata IP literals are always
+     * rejected regardless of the allowlist (SSRF defense-in-depth).
+     * Set to false only in controlled test environments.
+     */
+    blockPrivateHosts?: boolean;
+    /**
+     * Maximum number of UTF-8 bytes to include in `browser_read` results.
+     * Defaults to 512 KB. Content exceeding this limit is truncated with a marker.
+     */
+    maxContentBytes?: number;
+}
+/**
+ * Sealed browser-automation tools over an injected `PageLike` page.
+ *
+ * Returns an array of Eidentic `Tool` definitions:
+ *  - `browser_navigate` (destructive): validates URL + allowlist + private-host guard, then navigates.
+ *    After navigation, re-validates `page.url()` to detect redirect-based escapes.
+ *  - `browser_read` (read-only): returns page title + URL + innerText of a selector (or `body`),
+ *    truncated to `opts.maxContentBytes`.
+ *  - `browser_click` (destructive): clicks a CSS selector; selector errors are surfaced as tool errors.
+ *  - `browser_fill` (destructive): fills an input by CSS selector; selector errors are tool errors.
+ *
+ * Every tool receives the page at call time via the closure — no singleton page state is held.
+ *
+ * @example
+ * ```ts
+ * import { chromium } from "playwright-core";
+ * import { browserTools } from "@eidentic/browser";
+ * import { Agent } from "eidentic";
+ *
+ * const browser = await chromium.launch();
+ * const page = await browser.newPage();
+ *
+ * const agent = new Agent({
+ *   id: "web-agent",
+ *   model,
+ *   store,
+ *   tools: browserTools(page, { allowlist: ["example.com"] }),
+ * });
+ * ```
+ *
+ * @note No `browser_screenshot` tool in v1 — binary results don't compose with text tool results.
+ *   Roadmap: a future release will return a base64-encoded image string.
+ */
+declare function browserTools(page: PageLike, opts?: BrowserToolsOptions): Tool[];
+
+export { type BrowserToolsOptions, type PageLike, browserTools };

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import { Tool } from '@eidentic/core';
+export { hostAllowed, isBlockedHost } from '@eidentic/tools';
+
+/**
+ * Minimal structural interface for a browser page that `browserTools` can operate on.
+ *
+ * Designed as a strict subset of Playwright's `Page` type — a real `playwright-core`
+ * `Page` instance satisfies this interface without any adapter. You can also pass a
+ * faithful in-memory fake for tests (see `FakePage` in the test suite).
+ *
+ * `screenshot` is intentionally optional: it is NOT surfaced as a tool in v1 (binary
+ * results don't compose cleanly with text tool results). Roadmap: a future `browser_screenshot`
+ * tool returning a base64-encoded image string.
+ */
+interface PageLike {
+    /** Navigate to `url`. Returns when navigation is complete. */
+    goto(url: string): Promise<unknown>;
+    /** Return the full HTML content of the current page. */
+    content(): Promise<string>;
+    /** Return the innerText of the element matching `selector`. Throws if not found. */
+    innerText(selector: string): Promise<string>;
+    /** Click the element matching `selector`. */
+    click(selector: string): Promise<void>;
+    /** Fill an input element matching `selector` with `value`. */
+    fill(selector: string, value: string): Promise<void>;
+    /** Return the current page URL string. */
+    url(): string;
+    /** Return the page title. */
+    title(): Promise<string>;
+    /** Optional: capture a screenshot as raw bytes (not exposed as a tool in v1). Roadmap item. */
+    screenshot?(): Promise<Uint8Array>;
+}
+interface BrowserToolsOptions {
+    /**
+     * Egress allowlist of hostnames for browser navigation (§5.6 / §10.3). A host is allowed when
+     * it equals an entry OR is a subdomain of an entry (suffix match on a dot boundary).
+     *
+     * - **Omitted (`undefined`):** no domain restriction — any public http(s) host may be navigated to.
+     * - **Empty array (`[]`):** denies ALL navigation (explicit lockdown).
+     * - **Non-empty:** restricts navigation to the listed hosts (and their subdomains).
+     *
+     * In every mode, private / loopback / link-local / cloud-metadata hosts are ALWAYS rejected
+     * (SSRF defense, see `isBlockedHost` from `@eidentic/tools`).
+     *
+     * Every navigation, including model-driven `browser_navigate` calls, is re-validated:
+     * the tool validates the target URL before `goto()`, and then re-validates the URL reported
+     * by `page.url()` AFTER navigation completes — so redirect-based escapes are detected and
+     * surfaced as tool errors.
+     */
+    allowlist?: string[];
+    /**
+     * When true (default), private/loopback/link-local/cloud-metadata IP literals are always
+     * rejected regardless of the allowlist (SSRF defense-in-depth).
+     * Set to false only in controlled test environments.
+     */
+    blockPrivateHosts?: boolean;
+    /**
+     * Maximum number of UTF-8 bytes to include in `browser_read` results.
+     * Defaults to 512 KB. Content exceeding this limit is truncated with a marker.
+     */
+    maxContentBytes?: number;
+}
+/**
+ * Sealed browser-automation tools over an injected `PageLike` page.
+ *
+ * Returns an array of Eidentic `Tool` definitions:
+ *  - `browser_navigate` (destructive): validates URL + allowlist + private-host guard, then navigates.
+ *    After navigation, re-validates `page.url()` to detect redirect-based escapes.
+ *  - `browser_read` (read-only): returns page title + URL + innerText of a selector (or `body`),
+ *    truncated to `opts.maxContentBytes`.
+ *  - `browser_click` (destructive): clicks a CSS selector; selector errors are surfaced as tool errors.
+ *  - `browser_fill` (destructive): fills an input by CSS selector; selector errors are tool errors.
+ *
+ * Every tool receives the page at call time via the closure — no singleton page state is held.
+ *
+ * @example
+ * ```ts
+ * import { chromium } from "playwright-core";
+ * import { browserTools } from "@eidentic/browser";
+ * import { Agent } from "eidentic";
+ *
+ * const browser = await chromium.launch();
+ * const page = await browser.newPage();
+ *
+ * const agent = new Agent({
+ *   id: "web-agent",
+ *   model,
+ *   store,
+ *   tools: browserTools(page, { allowlist: ["example.com"] }),
+ * });
+ * ```
+ *
+ * @note No `browser_screenshot` tool in v1 — binary results don't compose with text tool results.
+ *   Roadmap: a future release will return a base64-encoded image string.
+ */
+declare function browserTools(page: PageLike, opts?: BrowserToolsOptions): Tool[];
+
+export { type BrowserToolsOptions, type PageLike, browserTools };

package/dist/index.js

@@ -0,0 +1,131 @@
+// src/index.ts
+import { z } from "zod";
+import { createTool } from "@eidentic/core";
+import { hostAllowed, isBlockedHost } from "@eidentic/tools";
+import { hostAllowed as hostAllowed2, isBlockedHost as isBlockedHost2 } from "@eidentic/tools";
+var DEFAULT_MAX_CONTENT_BYTES = 512 * 1024;
+var TRUNCATION_MARKER = "\n\u2026[content truncated]";
+function assertNavigableUrl(rawUrl, opts) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error(`browser: invalid URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`browser: only http(s) URLs are allowed (got ${parsed.protocol})`);
+  }
+  if (opts.blockPrivateHosts && isBlockedHost(parsed.hostname)) {
+    throw new Error(
+      `browser: host is a blocked private/loopback/metadata address: ${parsed.hostname}`
+    );
+  }
+  if (opts.allowlist !== void 0 && !hostAllowed(parsed.hostname, opts.allowlist)) {
+    throw new Error(
+      `browser: host not on allowlist: ${parsed.hostname}`
+    );
+  }
+  return parsed;
+}
+function truncateContent(text, maxBytes) {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= maxBytes) return text;
+  const markerBuf = Buffer.from(TRUNCATION_MARKER, "utf8");
+  const cutBytes = maxBytes - markerBuf.length;
+  return buf.subarray(0, cutBytes > 0 ? cutBytes : 0).toString("utf8") + TRUNCATION_MARKER;
+}
+function browserTools(page, opts) {
+  const blockPrivateHosts = opts?.blockPrivateHosts ?? true;
+  const maxContentBytes = opts?.maxContentBytes ?? DEFAULT_MAX_CONTENT_BYTES;
+  const guardOpts = { allowlist: opts?.allowlist, blockPrivateHosts };
+  const navigateTool = createTool({
+    id: "browser_navigate",
+    description: "Navigate the browser page to an http(s) URL. Only http(s) schemes are accepted. Private/loopback/metadata hosts are always rejected (SSRF defense). When an egress allowlist is configured, the host must be on it. After navigation, the final URL is re-validated to detect redirect-based escapes \u2014 the tool errors if the page was redirected off the allowlist.",
+    inputSchema: z.object({
+      url: z.string().describe("Absolute http(s) URL to navigate to")
+    }),
+    sideEffect: "destructive",
+    execute: async ({ input }) => {
+      assertNavigableUrl(input.url, guardOpts);
+      try {
+        await page.goto(input.url);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`browser_navigate: goto failed: ${msg}`);
+      }
+      const finalUrl = page.url();
+      try {
+        assertNavigableUrl(finalUrl, guardOpts);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `browser_navigate: redirect to blocked/disallowed URL detected after navigation: ${msg}`
+        );
+      }
+      return { navigated: true, url: finalUrl };
+    }
+  });
+  const readTool = createTool({
+    id: "browser_read",
+    description: "Read the current page's title, URL, and text content. When `selector` is provided, returns innerText of that element; otherwise returns innerText of the `body` element. Content is truncated to the configured `maxContentBytes` limit.",
+    inputSchema: z.object({
+      selector: z.string().optional().describe("CSS selector to read (defaults to `body` if omitted)")
+    }),
+    sideEffect: "read-only",
+    execute: async ({ input }) => {
+      const title = await page.title();
+      const url = page.url();
+      const sel = input.selector ?? "body";
+      let text;
+      try {
+        text = await page.innerText(sel);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `browser_read: innerText failed for selector "${sel}": ${msg}`, title, url };
+      }
+      const truncated = truncateContent(text, maxContentBytes);
+      return { title, url, text: truncated, truncated: truncated !== text };
+    }
+  });
+  const clickTool = createTool({
+    id: "browser_click",
+    description: "Click an element on the current page identified by a CSS selector. Selector errors (element not found, ambiguous) are surfaced as tool errors, not throws.",
+    inputSchema: z.object({
+      selector: z.string().describe("CSS selector of the element to click")
+    }),
+    sideEffect: "destructive",
+    execute: async ({ input }) => {
+      try {
+        await page.click(input.selector);
+        return { clicked: true, selector: input.selector };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `browser_click: click failed for selector "${input.selector}": ${msg}`, clicked: false };
+      }
+    }
+  });
+  const fillTool = createTool({
+    id: "browser_fill",
+    description: "Fill an input, textarea, or contenteditable element on the current page identified by a CSS selector. Selector errors are surfaced as tool errors, not throws.",
+    inputSchema: z.object({
+      selector: z.string().describe("CSS selector of the input element to fill"),
+      value: z.string().describe("Value to fill into the element")
+    }),
+    sideEffect: "destructive",
+    execute: async ({ input }) => {
+      try {
+        await page.fill(input.selector, input.value);
+        return { filled: true, selector: input.selector };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `browser_fill: fill failed for selector "${input.selector}": ${msg}`, filled: false };
+      }
+    }
+  });
+  return [navigateTool, readTool, clickTool, fillTool];
+}
+export {
+  browserTools,
+  hostAllowed2 as hostAllowed,
+  isBlockedHost2 as isBlockedHost
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@eidentic/browser",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eidentic/eidentic.git",
+    "directory": "packages/browser"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@eidentic/core": "0.1.0",
+    "@eidentic/tools": "0.1.0"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.40"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "playwright-core": "^1.52.0"
+  },
+  "description": "Sealed browser-automation tools for Eidentic — first-class sandboxed browser tools over an injected Playwright-like page (PageLike interface).",
+  "keywords": [
+    "ai",
+    "agents",
+    "typescript",
+    "eidentic",
+    "browser",
+    "playwright",
+    "automation",
+    "tools"
+  ],
+  "homepage": "https://github.com/eidentic/eidentic#readme",
+  "bugs": {
+    "url": "https://github.com/eidentic/eidentic/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit"
+  }
+}