browxai 0.7.0

package/dist/session/dialog.js

@@ -0,0 +1,164 @@
+// Per-session dialog policy. `alert` / `confirm` / `prompt` block every
+// subsequent browser event until handled — without a server-side listener, the
+// session deadlocks. This module installs `page.on('dialog')` per page on every
+// navigation/new-target and routes each fired dialog through a per-session
+// `DialogPolicyState`.
+//
+// Policy modes:
+//   - "accept"                       — accept every dialog (confirm/prompt → OK)
+//   - "dismiss"                      — dismiss every dialog (confirm/prompt → Cancel)
+//   - "accept-prompt-with:<text>"    — accept with the given text answer for
+//                                      prompts; accept for alert/confirm
+//   - "raise"  (DEFAULT)             — DISMISS the dialog server-side (so the
+//                                      page unblocks) but mark the action as
+//                                      failed with a structured failure hint,
+//                                      so a dialog never silently changes app
+//                                      state under an unaware caller.
+//
+// Per-action capture: every fired dialog is appended to a buffer with a
+// timestamp. `dialogsSince(ts)` slices the buffer for the action-window —
+// mirrors the ConsoleBuffer pattern. The `raise`-mode flag (`raisedSince(ts)`)
+// lets the action layer convert the action to `ok:false` without re-parsing
+// the dialog records.
+import { log } from "../util/logging.js";
+import { PolicyRecordBuffer } from "./policy-buffer.js";
+/** Hint emitted on `ActionResult.failure.hint` when `raise` mode fired.
+ *  Stable, agent-facing string — referenced in docs/tool-reference.md. */
+export const UNHANDLED_DIALOG_HINT = "unhandled dialog — set dialogPolicy (open_session/set_dialog_policy) to " +
+    '"accept", "dismiss", or "accept-prompt-with:<text>" before driving ' +
+    "an action that may trigger one. The dialog was dismissed server-side so " +
+    "the page is not deadlocked, but its app effect is the cancel branch.";
+/** Mutable per-session state. The handler reads `current()` on every fire,
+ *  so a `set_dialog_policy` call takes effect on the very next dialog. */
+export class DialogPolicyState {
+    policy;
+    /** Bounded record ring (shared `PolicyRecordBuffer` — the hard cap so a chatty
+     *  page can't grow this without bound; the per-action slice is the only
+     *  consumer, older records are noise). */
+    records;
+    /** Pages we've already installed the handler on. Lets the
+     *  `context.on('page')` wiring be idempotent — re-attaching to an existing
+     *  page (BYOB reconnect, profile-restore) doesn't double-fire. */
+    wired = new WeakSet();
+    constructor(initial = { mode: "raise" }, cap = 200) {
+        this.policy = normalise(initial);
+        this.records = new PolicyRecordBuffer(cap);
+    }
+    current() {
+        return { ...this.policy };
+    }
+    set(next) {
+        this.policy = normalise(next);
+        return this.current();
+    }
+    /** Append a dialog record. Caps the buffer at `cap`. */
+    record(rec) {
+        this.records.record(rec);
+    }
+    /** Slice records with `ts >= since`. Used by the action-window. */
+    since(since) {
+        return this.records.since(since);
+    }
+    /** True if any record in `[since, now]` was handled in `raise` mode.
+     *  When true, the action-window flips the result to `ok:false`. */
+    raisedSince(since) {
+        return this.records.matchedSince(since, (r) => r.handledAs === "raised");
+    }
+    /** Has this page already been wired? Idempotent install guard. */
+    hasPage(p) {
+        return this.wired.has(p);
+    }
+    /** Mark a page as wired. */
+    markPage(p) {
+        this.wired.add(p);
+    }
+}
+/** Parse the spec's compact string form (`"accept-prompt-with:<text>"`) into
+ *  the runtime `DialogPolicy` shape. Idempotent — also accepts the object form. */
+export function parseDialogPolicyArg(v) {
+    if (!v)
+        return { mode: "raise" };
+    if (typeof v === "object")
+        return normalise(v);
+    if (v === "accept" || v === "dismiss" || v === "raise")
+        return { mode: v };
+    if (v.startsWith("accept-prompt-with:")) {
+        const text = v.slice("accept-prompt-with:".length);
+        return { mode: "accept-prompt-with", text };
+    }
+    throw new Error(`dialogPolicy: invalid value "${v}" — expected "accept" | "dismiss" | "raise" | "accept-prompt-with:<text>"`);
+}
+function normalise(p) {
+    if (p.mode === "accept-prompt-with" && (p.text === undefined || p.text === null)) {
+        throw new Error('dialogPolicy: mode "accept-prompt-with" requires `text`');
+    }
+    return p.mode === "accept-prompt-with" ? { mode: p.mode, text: p.text } : { mode: p.mode };
+}
+/** Install the `page.on('dialog')` handler on a single page if not already
+ *  wired. Safe to call repeatedly; no-op when the page is already known. */
+export function installDialogHandler(page, state) {
+    if (state.hasPage(page))
+        return;
+    state.markPage(page);
+    page.on("dialog", (d) => {
+        handleDialog(d, state).catch((err) => {
+            // never throw out of an event handler — a dispatch error must not crash
+            // the page or the server. Log and move on; the next dialog reuses the
+            // same handler.
+            log.warn("session.dialog: handler error", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    });
+}
+/** Wire the dialog handler into every page in a context, plus a `context.on(
+ *  'page')` listener that wires future pages. Call once per session-creation;
+ *  the `context.on('page')` install is idempotent because `installDialogHandler`
+ *  short-circuits already-wired pages. */
+export function attachDialogPolicy(context, state) {
+    for (const page of context.pages())
+        installDialogHandler(page, state);
+    context.on("page", (page) => installDialogHandler(page, state));
+}
+async function handleDialog(d, state) {
+    const policy = state.current();
+    const kind = d.type();
+    const message = d.message();
+    const defaultValue = d.defaultValue() || undefined;
+    const ts = Date.now();
+    switch (policy.mode) {
+        case "accept": {
+            // For alert: accept (no-op). For confirm: OK. For prompt: empty answer.
+            // Callers who want a specific prompt answer set "accept-prompt-with".
+            await d.accept().catch(() => undefined);
+            state.record({ kind, message, defaultValue, handledAs: "accepted", ts });
+            return;
+        }
+        case "dismiss": {
+            await d.dismiss().catch(() => undefined);
+            state.record({ kind, message, defaultValue, handledAs: "dismissed", ts });
+            return;
+        }
+        case "accept-prompt-with": {
+            // Only prompts read the text answer; alert/confirm ignore the second arg
+            // — Playwright accepts either with or without the prompt text.
+            const text = policy.text ?? "";
+            if (kind === "prompt") {
+                await d.accept(text).catch(() => undefined);
+            }
+            else {
+                await d.accept().catch(() => undefined);
+            }
+            state.record({ kind, message, defaultValue, handledAs: "accepted", ts });
+            return;
+        }
+        case "raise":
+        default: {
+            // Dismiss server-side so the page unblocks (the spec's anti-deadlock
+            // guarantee) AND mark the action as failed via the buffer flag.
+            await d.dismiss().catch(() => undefined);
+            state.record({ kind, message, defaultValue, handledAs: "raised", ts });
+            return;
+        }
+    }
+}

package/dist/session/emulation.d.ts

@@ -0,0 +1,69 @@
+import type { BrowserContext, CDPSession, Page } from "playwright-core";
+export type ColorScheme = "light" | "dark" | "no-preference";
+export type ReducedMotion = "reduce" | "no-preference";
+export interface GeolocationCoords {
+    latitude: number;
+    longitude: number;
+    /** metres; Playwright default 0. */
+    accuracy?: number;
+}
+/** Per-origin permission grant. `origin` empty/undefined → applies to the
+ *  current page's origin at apply time. */
+export interface PermissionGrant {
+    permissions: string[];
+    origin?: string;
+}
+/** Mutable bag of resolved emulation state. Stored per `SessionEntry`. Any
+ *  field that is `undefined` means "no override — use the browser default". */
+export interface EmulationState {
+    locale?: string;
+    timezoneId?: string;
+    geolocation?: GeolocationCoords;
+    colorScheme?: ColorScheme;
+    reducedMotion?: ReducedMotion;
+    userAgent?: string;
+    /** Per-origin permission grants, keyed by origin (empty string = "current
+     *  page origin at apply time"). Each grant REPLACES the prior set for that
+     *  origin — Playwright's `context.grantPermissions` is itself replace-not-
+     *  merge per call, so we mirror its semantics. */
+    permissions: Map<string, string[]>;
+}
+export declare function newEmulationState(): EmulationState;
+/** Re-apply every set knob to a freshly attached page/context. Used on
+ *  `BrowserContext.on("page")` and on session re-attach. Best-effort: each
+ *  applier swallows its own error and the next still runs.
+ *
+ *  `cdpFor(page)` returns the CDP session for the page — owned by the caller
+ *  (the registry creates one CDP session per primary page). For secondary
+ *  pages opened via `on("page")`, the caller passes a freshly-created CDP. */
+export declare function reapplyAll(context: BrowserContext, page: Page, cdp: CDPSession, state: EmulationState): Promise<void>;
+/** `Emulation.setLocaleOverride` — moves the `Accept-Language` header AND the
+ *  ICU/`Intl` default locale. It does NOT change `navigator.language` /
+ *  `navigator.languages` (those are JS getters fixed at document creation), so a
+ *  full locale emulation pairs this with `applyLocaleNavigator`. Passing empty
+ *  string clears the override (CDP semantics). */
+export declare function applyLocaleCdp(cdp: CDPSession, locale: string): Promise<void>;
+export declare function clearLocaleCdp(cdp: CDPSession): Promise<void>;
+/** Companion to `applyLocaleCdp`: patch the JS `navigator.language(s)` signal.
+ *  Registers a context-level init script (future documents + new tabs inherit
+ *  it) AND re-runs it in the current document for immediate effect. Pass an empty
+ *  locale to restore the captured originals. */
+export declare function applyLocaleNavigator(context: BrowserContext, page: Page, locale: string): Promise<void>;
+export declare function applyTimezoneCdp(cdp: CDPSession, timezoneId: string): Promise<void>;
+export declare function clearTimezoneCdp(cdp: CDPSession): Promise<void>;
+export declare function applyGeolocation(context: BrowserContext, coords: GeolocationCoords): Promise<void>;
+export declare function clearGeolocation(context: BrowserContext): Promise<void>;
+export declare function applyColorScheme(page: Page, scheme: ColorScheme): Promise<void>;
+export declare function applyReducedMotion(page: Page, motion: ReducedMotion): Promise<void>;
+export declare function applyUserAgentCdp(cdp: CDPSession, userAgent: string): Promise<void>;
+export declare function clearUserAgentCdp(cdp: CDPSession): Promise<void>;
+/** Replace the grant for a single origin (or "" = current page origin).
+ *  Updates the state bag, then issues the Playwright call. */
+export declare function applyPermissions(context: BrowserContext, state: EmulationState, permissions: string[], origin?: string): Promise<void>;
+export declare function clearPermissions(context: BrowserContext, state: EmulationState, origin?: string): Promise<void>;
+/** Distinct-warning helper. BYOB / attached sessions push CDP overrides into
+ *  Chrome that browxai does NOT own and CANNOT undo on detach in every case
+ *  (the human's browser keeps the override until they navigate / restart).
+ *  Tools surface this string in their result `warnings` whenever an emulation
+ *  override is applied to an attached session. */
+export declare const BYOB_EMULATION_WARNING: string;

package/dist/session/emulation.js

@@ -0,0 +1,168 @@
+// Per-primitive device-emulation state + appliers.
+//
+// Sits alongside `device.ts` (which resolves a Playwright preset at *context-
+// creation* time). The primitives here are the runtime-mutable surface: 7 MCP
+// tools that each set ONE Playwright/CDP emulation knob on a live session, so
+// agents don't have to over-specify a bundled `emulate({...})` payload on
+// every call.
+//
+// Persistence model. Each setting's resolved value is stored on the
+// `SessionEntry.deviceEmulation` bag for the session's lifetime. One re-apply
+// path: new page in the same context — a `BrowserContext.on("page")` hook
+// re-runs the applier so a tab opened mid-session inherits the overrides.
+//
+// Runtime-vs-context-time. Playwright's `BrowserContext` bakes some options
+// (`locale`, `timezoneId`, `userAgent`) at creation; there is no public mutator
+// for them on an existing context. CDP `Emulation.setLocaleOverride`,
+// `Emulation.setTimezoneOverride`, and `Network.setUserAgentOverride` DO take
+// effect post-creation, so this module routes those three through the
+// per-page CDP session. The remaining four — geolocation, colour scheme,
+// reduced motion, permissions — have stable Playwright mid-session mutators
+// and use those. See per-applier comments for the exact mechanism.
+export function newEmulationState() {
+    return { permissions: new Map() };
+}
+/** Re-apply every set knob to a freshly attached page/context. Used on
+ *  `BrowserContext.on("page")` and on session re-attach. Best-effort: each
+ *  applier swallows its own error and the next still runs.
+ *
+ *  `cdpFor(page)` returns the CDP session for the page — owned by the caller
+ *  (the registry creates one CDP session per primary page). For secondary
+ *  pages opened via `on("page")`, the caller passes a freshly-created CDP. */
+export async function reapplyAll(context, page, cdp, state) {
+    if (state.locale !== undefined)
+        await applyLocaleCdp(cdp, state.locale).catch(() => undefined);
+    if (state.timezoneId !== undefined)
+        await applyTimezoneCdp(cdp, state.timezoneId).catch(() => undefined);
+    if (state.userAgent !== undefined)
+        await applyUserAgentCdp(cdp, state.userAgent).catch(() => undefined);
+    if (state.geolocation !== undefined)
+        await applyGeolocation(context, state.geolocation).catch(() => undefined);
+    if (state.colorScheme !== undefined)
+        await applyColorScheme(page, state.colorScheme).catch(() => undefined);
+    if (state.reducedMotion !== undefined)
+        await applyReducedMotion(page, state.reducedMotion).catch(() => undefined);
+    for (const [origin, perms] of state.permissions) {
+        const opts = origin ? { origin } : undefined;
+        await context.grantPermissions(perms, opts).catch(() => undefined);
+    }
+}
+// ---------------- locale (CDP override + navigator patch) ----------------
+/** `Emulation.setLocaleOverride` — moves the `Accept-Language` header AND the
+ *  ICU/`Intl` default locale. It does NOT change `navigator.language` /
+ *  `navigator.languages` (those are JS getters fixed at document creation), so a
+ *  full locale emulation pairs this with `applyLocaleNavigator`. Passing empty
+ *  string clears the override (CDP semantics). */
+export async function applyLocaleCdp(cdp, locale) {
+    await cdp.send("Emulation.setLocaleOverride", { locale });
+}
+export async function clearLocaleCdp(cdp) {
+    // Per CDP, omitting `locale` clears the override. Playwright's send() is
+    // strict-typed so we pass empty-string which the protocol treats as clear.
+    await cdp.send("Emulation.setLocaleOverride", { locale: "" });
+}
+/** BCP-47 tag → a `navigator.languages` chain: "fr-FR" → ["fr-FR","fr"]. */
+function localeChain(locale) {
+    const base = locale.split("-")[0];
+    return base && base !== locale ? [locale, base] : [locale];
+}
+/** The page-side patch that makes `navigator.language` / `navigator.languages`
+ *  report the emulated locale — the JS signal `setLocaleOverride` leaves alone.
+ *  Idempotent via a window flag: the first run captures the originals and
+ *  installs configurable getters; every run only updates the value, so repeated
+ *  `set_locale` calls (and the context re-running the script on new documents)
+ *  never stack property redefinitions. An empty locale restores the original. */
+function localeNavigatorScript(locale) {
+    const value = locale ? JSON.stringify(locale) : "null";
+    const list = locale ? JSON.stringify(localeChain(locale)) : "null";
+    return `(() => {
+  const w = window;
+  if (!w.__browxLocale) {
+    w.__browxLocale = {
+      lang: navigator.language,
+      langs: Array.prototype.slice.call(navigator.languages),
+    };
+    Object.defineProperty(navigator, "language", {
+      configurable: true,
+      get: () => (w.__browxLocale.override === undefined ? w.__browxLocale.lang : w.__browxLocale.override),
+    });
+    Object.defineProperty(navigator, "languages", {
+      configurable: true,
+      get: () => (w.__browxLocale.overrideList === undefined ? w.__browxLocale.langs : w.__browxLocale.overrideList),
+    });
+  }
+  w.__browxLocale.override = ${value} === null ? undefined : ${value};
+  w.__browxLocale.overrideList = ${list} === null ? undefined : ${list};
+})();`;
+}
+/** Companion to `applyLocaleCdp`: patch the JS `navigator.language(s)` signal.
+ *  Registers a context-level init script (future documents + new tabs inherit
+ *  it) AND re-runs it in the current document for immediate effect. Pass an empty
+ *  locale to restore the captured originals. */
+export async function applyLocaleNavigator(context, page, locale) {
+    const script = localeNavigatorScript(locale);
+    await context.addInitScript({ content: script });
+    await page.evaluate(script).catch(() => undefined);
+}
+// ---------------- timezone (CDP-only mid-session) ----------------
+export async function applyTimezoneCdp(cdp, timezoneId) {
+    await cdp.send("Emulation.setTimezoneOverride", { timezoneId });
+}
+export async function clearTimezoneCdp(cdp) {
+    await cdp.send("Emulation.setTimezoneOverride", { timezoneId: "" });
+}
+// ---------------- geolocation (Playwright context mutator) ----------------
+export async function applyGeolocation(context, coords) {
+    await context.setGeolocation({
+        latitude: coords.latitude,
+        longitude: coords.longitude,
+        accuracy: coords.accuracy ?? 0,
+    });
+}
+export async function clearGeolocation(context) {
+    await context.setGeolocation(null);
+}
+// ---------------- colour scheme (Playwright page mutator) ----------------
+export async function applyColorScheme(page, scheme) {
+    await page.emulateMedia({ colorScheme: scheme });
+}
+// ---------------- reduced motion (Playwright page mutator) ----------------
+export async function applyReducedMotion(page, motion) {
+    await page.emulateMedia({ reducedMotion: motion });
+}
+// ---------------- user agent (CDP-only mid-session) ----------------
+export async function applyUserAgentCdp(cdp, userAgent) {
+    await cdp.send("Network.setUserAgentOverride", { userAgent });
+}
+export async function clearUserAgentCdp(cdp) {
+    // Empty-string clears the override per CDP.
+    await cdp.send("Network.setUserAgentOverride", { userAgent: "" });
+}
+// ---------------- permissions ----------------
+/** Replace the grant for a single origin (or "" = current page origin).
+ *  Updates the state bag, then issues the Playwright call. */
+export async function applyPermissions(context, state, permissions, origin) {
+    const key = origin ?? "";
+    state.permissions.set(key, [...permissions]);
+    const opts = origin ? { origin } : undefined;
+    await context.grantPermissions(permissions, opts);
+}
+export async function clearPermissions(context, state, origin) {
+    // Playwright doesn't expose per-origin permission revocation — only the
+    // context-wide `clearPermissions`. We mirror that semantics: clearing wipes
+    // every grant in the state bag and the context.
+    state.permissions.clear();
+    if (origin !== undefined) {
+        // Caller asked to clear ONE origin; we issued a full clear because the
+        // platform doesn't support partial — surface as a warning at the tool layer.
+    }
+    await context.clearPermissions();
+}
+/** Distinct-warning helper. BYOB / attached sessions push CDP overrides into
+ *  Chrome that browxai does NOT own and CANNOT undo on detach in every case
+ *  (the human's browser keeps the override until they navigate / restart).
+ *  Tools surface this string in their result `warnings` whenever an emulation
+ *  override is applied to an attached session. */
+export const BYOB_EMULATION_WARNING = "BYOB caveat: this emulation override is applied via CDP to an attached " +
+    "(not-owned) Chrome and will PERSIST on that browser after browxai " +
+    "detaches. The human's Chrome must navigate / restart to fully clear it.";

package/dist/session/extensions.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Loaded-extension record. `id` is the Chrome-computed extension id (a 32-char
+ * lowercase alpha string derived from the unpacked path; deterministic given
+ * the same path). `path` is the resolved absolute path on disk. `enabled` is
+ * a registry-level flag — disabling without uninstall is currently a no-op
+ * because Chrome won't honour a partial extension list mid-launch; reserved
+ * for a future contract.
+ */
+export interface LoadedExtension {
+    id: string;
+    name: string;
+    version: string;
+    path: string;
+    enabled: boolean;
+}
+/** Per-session extension state. Lives on `SessionEntry.extensions`. */
+export interface ExtensionRegistry {
+    /** Currently-loaded extensions for this session. Empty by default. */
+    loaded: LoadedExtension[];
+}
+export declare function newExtensionRegistry(): ExtensionRegistry;
+/** Result envelope for install / reload / uninstall — the standard ok/error
+ *  shape the tool layer wraps with `tokensEstimate`. */
+export interface ExtensionMutationResult {
+    ok: true;
+    loaded: LoadedExtension[];
+    /** Optional note surfaced to the agent (rebuild warning, etc.). */
+    note?: string;
+}
+/**
+ * Resolve a caller-supplied `path` to an absolute workspace-rooted directory
+ * containing an MV3 (or MV2) manifest. Rejects:
+ *   - empty / whitespace
+ *   - traversal segments (`..`) that escape the workspace
+ *   - absolute paths pointing outside the workspace
+ *   - non-existent paths
+ *   - paths that are files (not a directory)
+ *   - directories missing `manifest.json`
+ *
+ * Returns the resolved absolute path. Throws `Error` with a structured message
+ * on any rejection — the tool handler converts that to the `ok:false` envelope.
+ */
+export declare function resolveExtensionPath(workspaceRoot: string, p: string, tool: string): string;
+/** Parsed extension manifest — the minimal subset we surface to the agent. */
+export interface ParsedManifest {
+    name: string;
+    version: string;
+    manifestVersion: number;
+}
+export declare function readManifest(extPath: string, tool: string): ParsedManifest;
+/**
+ * Compute a deterministic, stable id for an unpacked extension keyed off its
+ * absolute path. Chrome's real algorithm hashes the path with SHA-256 and
+ * maps the first 16 bytes onto the alphabet `a-p` (32 chars). We approximate
+ * with a 32-char alpha hash that's deterministic across runs given the same
+ * path; the *exact* Chrome id is not required for our use cases (list /
+ * reload / uninstall / trigger all key off the path or our own id mapping).
+ *
+ * The hash uses Node's built-in `node:crypto` — no extra dep.
+ */
+export declare function extensionIdFromPath(absPath: string): string;
+/** Build the Chromium launch arguments for a given set of enabled extensions.
+ *  Empty list → empty args (no extension flags). Returns a frozen array. */
+export declare function buildLaunchArgs(loaded: ReadonlyArray<LoadedExtension>): string[];
+/** Sentinel returned by the refuse predicates so the tool layer surfaces a
+ *  uniform error envelope. */
+export interface RefuseResult {
+    ok: false;
+    error: string;
+    hint: string;
+}
+/**
+ * Pure refusal predicate — returns null when the session can host extensions,
+ * else a structured rejection. Mirrors the gate pattern in server.ts but is
+ * pure (testable without launching Chrome).
+ */
+export declare function refuseIfUnsupported(input: {
+    mode: "persistent" | "incognito" | "attached";
+    headless: boolean;
+    tool: string;
+}): RefuseResult | null;
+/**
+ * In-place mutation helper for the install operation. Pure — given the
+ * current registry and a resolved + parsed install request, returns the new
+ * registry. Throws on duplicate path. The tool layer is responsible for the
+ * rebuild step that materialises the change.
+ */
+export declare function applyInstall(reg: ExtensionRegistry, install: {
+    path: string;
+    name: string;
+    version: string;
+}, tool: string): {
+    id: string;
+    loaded: LoadedExtension[];
+};
+/**
+ * Pure helper for uninstall — returns the next loaded list, throws when the
+ * id isn't loaded.
+ */
+export declare function applyUninstall(reg: ExtensionRegistry, id: string, tool: string): {
+    loaded: LoadedExtension[];
+    removed: LoadedExtension;
+};
+/**
+ * Pure helper for reload — re-parses the manifest at the loaded path and
+ * returns the next loaded list with updated name/version. The browser-context
+ * rebuild is what actually re-injects content scripts; this helper just keeps
+ * the registry consistent.
+ */
+export declare function applyReload(reg: ExtensionRegistry, id: string, parsed: ParsedManifest, tool: string): {
+    loaded: LoadedExtension[];
+    entry: LoadedExtension;
+};