browxai 0.7.0

package/dist/tools/read-observe-verify-tools.js

@@ -0,0 +1,316 @@
+import { requireCdp } from "../engine/index.js";
+import { verifyVisible, verifyText, verifyValue, verifyCount, verifyAttribute, verifyPredicate, } from "../page/verify.js";
+import { withDeadline } from "../util/deadline.js";
+import { estimateTokens } from "../util/tokens.js";
+import { REF_OR_SELECTOR, SESSION_ARG } from "./schemas.js";
+/**
+ * Read / observe — the assertive verify_* family. Fail-emitting siblings of
+ * `wait_for`: each asserts a page condition NOW and returns `ok:false` with a
+ * structured `failure` on a miss. Read-only; registered through the shared
+ * `ToolHost` seam.
+ */
+export function registerReadObserveVerifyTools(host) {
+    const { z, register, gateCheck, entryFor, asTarget, cfgActionTimeout, caps, config } = host;
+    // ---------- verify-family — assertive read primitives ----------
+    // Shared inputs for the element-targeted verify_* tools. Same target shape
+    // as the action surface (ref / selector / named — coords not allowed; a
+    // verify needs a structural identity, not a pixel).
+    const VERIFY_TARGET = {
+        ref: REF_OR_SELECTOR.ref,
+        selector: REF_OR_SELECTOR.selector,
+        named: REF_OR_SELECTOR.named,
+        contextRef: REF_OR_SELECTOR.contextRef,
+        ...SESSION_ARG,
+    };
+    /** Wrap a `VerifyResult` in the standard JSON envelope with `tokensEstimate`.
+     *  Same `{ok, failure}` shape across the whole family.
+     *
+     *  Secrets-masking: when `e` is supplied and the `secrets` capability is on,
+     *  the body is run through `applyMaskDeep` BEFORE token-counting and
+     *  envelope construction. The load-bearing path is `failure.actual` for
+     *  `verify_text` / `verify_value` / `verify_attribute` — these echo the
+     *  element's real innerText / value / attribute on a miss, which is a
+     *  direct value-disclosure of any registered secret. Callers that don't
+     *  thread a session entry (no page-derived strings) pass `undefined`. */
+    const verifyResultText = (res, e) => {
+        const rawBody = res.ok ? { ok: true } : { ok: false, failure: res.failure };
+        const body = e && caps.enabled.has("secrets") ? e.secrets.applyMaskDeep(rawBody) : rawBody;
+        const tokensEstimate = estimateTokens(JSON.stringify(body));
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+            ],
+        };
+    };
+    register("verify_visible", {
+        capability: "read",
+        batchable: true,
+        description: 'Assertive sibling of `wait_for`: fail-emitting (`ok:false` + `failure:{source,kind,expected,actual}`) instead of permissive (`wait_for` returns ok:false on deadline expiry as a normal outcome). Use to terminate retry loops deterministically: "this element MUST be visible right now, else fail loudly." Read-only. `source:"app"` when the element isn\'t visible (the assertion failed against the page); `source:"browxai"` when verify itself couldn\'t run (ref no longer in the snapshot, etc).',
+        inputSchema: VERIFY_TARGET,
+    }, async (args) => {
+        const g = gateCheck("verify_visible");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const target = asTarget(args, "verify_visible", e.refs);
+        if ("coords" in target) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "visible",
+                    expected: "ref/selector/named target",
+                    actual: "coords target",
+                },
+            }, e);
+        }
+        try {
+            const res = await withDeadline(verifyVisible(e.session.page(), e.refs, target), cfgActionTimeout(), "verify_visible");
+            return verifyResultText(res, e);
+        }
+        catch (err) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "visible",
+                    expected: "verify_visible to complete",
+                    actual: err instanceof Error ? err.message : String(err),
+                },
+            }, e);
+        }
+    });
+    register("verify_text", {
+        capability: "read",
+        batchable: true,
+        description: "Assert the targeted element's visible text matches. Fail-emitting (`ok:false` + structured `failure`) — distinct from `text_search` (which counts matches over the whole page) and `wait_for` (permissive). Default substring + case-insensitive; pass `exact:true` for case-sensitive equality on the trimmed text. Read-only.",
+        inputSchema: {
+            ...VERIFY_TARGET,
+            text: z.string().describe("Text to assert against the element's visible text."),
+            exact: z
+                .boolean()
+                .optional()
+                .describe("Default false (case-insensitive substring). When true, case-sensitive equality on trimmed innerText."),
+        },
+    }, async (args) => {
+        const g = gateCheck("verify_text");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const target = asTarget(args, "verify_text", e.refs);
+        if ("coords" in target) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "text",
+                    expected: "ref/selector/named target",
+                    actual: "coords target",
+                },
+            }, e);
+        }
+        try {
+            const res = await withDeadline(verifyText(e.session.page(), e.refs, target, args.text, args.exact === true), cfgActionTimeout(), "verify_text");
+            return verifyResultText(res, e);
+        }
+        catch (err) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "text",
+                    expected: "verify_text to complete",
+                    actual: err instanceof Error ? err.message : String(err),
+                },
+            }, e);
+        }
+    });
+    register("verify_value", {
+        capability: "read",
+        batchable: true,
+        description: "Assert the targeted form-control's current value (input/textarea/select/contenteditable). Fail-emitting (`ok:false` + structured `failure`). Use to confirm a controlled-component fill landed without an extra round-trip — pairs with `ActionResult.element.value` from `fill`. Read-only.",
+        inputSchema: {
+            ...VERIFY_TARGET,
+            value: z
+                .string()
+                .describe("Expected value (strict equality after String() of the DOM-side `value`)."),
+        },
+    }, async (args) => {
+        const g = gateCheck("verify_value");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const target = asTarget(args, "verify_value", e.refs);
+        if ("coords" in target) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "value",
+                    expected: "ref/selector/named target",
+                    actual: "coords target",
+                },
+            }, e);
+        }
+        try {
+            const res = await withDeadline(verifyValue(e.session.page(), e.refs, target, args.value), cfgActionTimeout(), "verify_value");
+            return verifyResultText(res, e);
+        }
+        catch (err) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "value",
+                    expected: "verify_value to complete",
+                    actual: err instanceof Error ? err.message : String(err),
+                },
+            }, e);
+        }
+    });
+    register("verify_count", {
+        capability: "read",
+        batchable: true,
+        description: 'Assert exactly `n` elements match. Pass one of `selector` (raw CSS / Playwright locator) or `text` (case-insensitive visible-text search over the composed a11y tree, same shape as `text_search`). Fail-emitting (`ok:false` + structured `failure`). Use for grid/list invariants — "there are 5 rows after the delete", "no \'Wrong Type\' values left in the table". Read-only.',
+        inputSchema: {
+            selector: z
+                .string()
+                .optional()
+                .describe("CSS / selectorHint to count. Mutually exclusive with `text`."),
+            text: z
+                .string()
+                .optional()
+                .describe("Visible text to count (case-insensitive substring across the a11y tree)."),
+            n: z.number().int().nonnegative().describe("Exact expected count."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("verify_count");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        try {
+            const res = await withDeadline(verifyCount(e.session.page(), requireCdp(e.session), e.refs, {
+                selector: args.selector,
+                text: args.text,
+                n: args.n,
+                testAttributes: config.testAttributes,
+            }), cfgActionTimeout(), "verify_count");
+            return verifyResultText(res, e);
+        }
+        catch (err) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "count",
+                    expected: "verify_count to complete",
+                    actual: err instanceof Error ? err.message : String(err),
+                },
+            }, e);
+        }
+    });
+    register("verify_attribute", {
+        capability: "read",
+        batchable: true,
+        description: "Assert the targeted element's HTML attribute matches. Pass `value` to require equality; omit `value` to require presence (any value). Fail-emitting (`ok:false` + structured `failure`). Use for `aria-*` / `data-*` / `disabled` / role state that doesn't surface as visible text. Read-only.",
+        inputSchema: {
+            ...VERIFY_TARGET,
+            attr: z
+                .string()
+                .describe('Attribute name to read (e.g. "aria-pressed", "data-state", "disabled").'),
+            value: z
+                .string()
+                .optional()
+                .describe("Expected attribute value (strict string equality). Omit to assert the attribute is merely present."),
+        },
+    }, async (args) => {
+        const g = gateCheck("verify_attribute");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const target = asTarget(args, "verify_attribute", e.refs);
+        if ("coords" in target) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "attribute",
+                    expected: "ref/selector/named target",
+                    actual: "coords target",
+                },
+            }, e);
+        }
+        try {
+            const res = await withDeadline(verifyAttribute(e.session.page(), e.refs, target, args.attr, args.value), cfgActionTimeout(), "verify_attribute");
+            return verifyResultText(res, e);
+        }
+        catch (err) {
+            return verifyResultText({
+                ok: false,
+                failure: {
+                    source: "browxai",
+                    kind: "attribute",
+                    expected: "verify_attribute to complete",
+                    actual: err instanceof Error ? err.message : String(err),
+                },
+            }, e);
+        }
+    });
+    // Recursive predicate shape — z.lazy lets the schema reference itself for
+    // the and/or/not combinators. NOT an arbitrary-JS path: the `kind` enum and
+    // `key` accessor list are fixed server-side (see src/util/predicates.ts).
+    const PREDICATE_SCHEMA = z.lazy(() => z.union([
+        z.object({
+            kind: z.enum([
+                "equals",
+                "notEquals",
+                "contains",
+                "notContains",
+                "gt",
+                "lt",
+                "gte",
+                "lte",
+                "matches",
+                "exists",
+            ]),
+            key: z
+                .string()
+                .describe('Dotted accessor into `data` (e.g. "actionResult.element.value"). Must start with an allow-listed root (actionResult, snapshot, element, value, expect).'),
+            value: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+        }),
+        z.object({
+            kind: z.literal("between"),
+            key: z.string(),
+            lo: z.number(),
+            hi: z.number(),
+        }),
+        z.object({
+            kind: z.enum(["and", "or", "not"]),
+            predicates: z.array(PREDICATE_SCHEMA).min(1),
+        }),
+    ]));
+    register("verify_predicate", {
+        capability: "read",
+        batchable: true,
+        description: 'Composed predicate check over a caller-supplied `data` bag — fixed vocabulary, NOT arbitrary JS. The predicate `kind` is a fixed enum (`equals`/`notEquals`/`contains`/`notContains`/`gt`/`lt`/`gte`/`lte`/`between`/`matches`/`exists`, plus `and`/`or`/`not` combinators). The accessor `key` must start with an allow-listed root: `actionResult`, `snapshot`, `element`, `value`, `expect`. The model supplies *data* (which key, which expected value); the *vocabulary* is server-owned. Use as a deterministic gate on an already-captured ActionResult / snapshot / metric (the screenshot-judge analogue when chained behind a `screenshot`). Fail-emitting: `source:"app"` when the predicate didn\'t hold; `source:"browxai"` when the predicate shape itself is malformed. `eval_js` (gated behind `eval`) remains the only arbitrary-JS path — verify_predicate does NOT add a second.',
+        inputSchema: {
+            predicate: PREDICATE_SCHEMA.describe("The predicate to evaluate. Recursive shape — and/or/not nest leaf predicates."),
+            data: z
+                .record(z.unknown())
+                .describe("Bag the predicate reads from. Typically `{ actionResult: <prior result>, snapshot?: <prior snapshot output>, element?: {...} }`. Accessor keys are resolved against this object; only allow-listed root segments are honoured."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("verify_predicate");
+        if (g)
+            return g;
+        // Resolve the session entry so `failure.actual` (which may echo a
+        // string lifted from the caller-supplied `data` bag — e.g. a prior
+        // ActionResult.element.value that pre-dated masking) gets re-masked
+        // through the same egress chokepoint as the other verify_* tools.
+        const e = await entryFor(args.session);
+        const res = verifyPredicate(args.predicate, args.data);
+        return verifyResultText(res, e);
+    });
+}

package/dist/tools/schemas.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const SESSION_ARG: {
+    session: z.ZodOptional<z.ZodString>;
+};
+export declare const TIMEOUT_ARG: {
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+};
+export declare const ACTION_OPTS: {
+    session: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<["scoped_snapshot", "tree_diff", "full", "none"]>>;
+    maxResultTokens: z.ZodOptional<z.ZodNumber>;
+};
+export declare const REF_OR_SELECTOR: {
+    ref: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    named: z.ZodOptional<z.ZodString>;
+    contextRef: z.ZodOptional<z.ZodString>;
+    coords: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        y: number;
+        x: number;
+    }, {
+        y: number;
+        x: number;
+    }>>;
+};

package/dist/tools/schemas.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+// Shared input-schema fragments for the MCP tool surface. These live in a leaf
+// module — depended on by both the composition root (`createServer`) and the
+// per-family tool modules under `src/tools/` — so neither side has to import the
+// other. Keeping them here is what lets `action-tools.ts` depend on the host
+// seam alone instead of reaching back into `../server.js` (which would close an
+// import cycle).
+const SNAPSHOT_MODE = z.enum(["scoped_snapshot", "tree_diff", "full", "none"]).optional();
+// every browser-touching tool accepts an optional `session` id.
+// Omitting it resolves to the lazily-created "default" session — byte-identical
+// to pre-2.5 single-session behaviour. Distinct ids get fully isolated state
+// (own RefRegistry, own BrowserContext / cookie jar, own buffers).
+export const SESSION_ARG = {
+    session: z
+        .string()
+        .optional()
+        .describe('Session id (default "default"). Each id is an isolated browser context (own cookie jar, own refs). Open non-default sessions with open_session; list with list_sessions.'),
+};
+// per-call anti-wedge override. Default comes from config
+// `actionTimeoutMs` (5000). The wording deliberately deters large values.
+export const TIMEOUT_ARG = {
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(3_600_000)
+        .optional()
+        .describe("Anti-wedge hard deadline for this call (ms). Default 5000 (config `actionTimeoutMs`). " +
+        "An action needing >5s is almost always a no-op or a wedged page op. When a call " +
+        "times out, the fix is to retry it ONCE or — if timeouts keep recurring — discard " +
+        "the session (`close_session` then `open_session`), NOT a bigger timeout: raising " +
+        "this never recovers a wedged session. Raise it ONLY for one specific known-slow " +
+        "call, never as a blanket. Values approaching the 3600000 (1h) ceiling are " +
+        "essentially always a mistake; over-ceiling is clamped + warned."),
+};
+export const ACTION_OPTS = {
+    mode: SNAPSHOT_MODE,
+    maxResultTokens: z.number().int().positive().max(20_000).optional(),
+    ...TIMEOUT_ARG,
+    ...SESSION_ARG,
+};
+// `target` accepts ref *or* selector *or* named *or* coords. Validated at
+// handler time. `contextRef` optionally scopes a `selector` to a prior ref's
+// subtree. `coords` is the escape hatch for visually-located targets (canvas,
+// custom-painted UIs, dismiss-empty-space) — only click/hover honour it.
+export const REF_OR_SELECTOR = {
+    ref: z.string().optional().describe("Stable [eN] ref from snapshot()/find()"),
+    selector: z.string().optional().describe("CSS / selectorHint fallback"),
+    named: z.string().optional().describe("Mnemonic name previously bound with name_ref"),
+    contextRef: z
+        .string()
+        .optional()
+        .describe("Resolve `selector` within the subtree of this ref (from a prior snapshot/find). Lets you say 'the X *inside* this row/card/panel' without baking positional :nth chains into the selector. Ignored when `ref` or `named` is used."),
+    coords: z
+        .object({ x: z.number(), y: z.number() })
+        .optional()
+        .describe("Page-coordinate target {x,y} (CSS pixels, viewport-relative). Escape hatch for canvas / custom-painted UIs / dismiss-empty-space cases that ref/selector resolution can't address. Honoured by `click` and `hover` only; ignored elsewhere."),
+};

package/dist/tools/secrets-captcha-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Secrets / captcha / credentials tools — the off-by-default egress-sensitive
+ * seams: `register_secret` (the per-session secrets registry that backs egress
+ * masking), `solve_captcha` (the provider-bridge), and `get_totp` /
+ * `get_credential` (the credentials provider). Registered through the shared
+ * `ToolHost` seam.
+ */
+export declare function registerSecretsCaptchaTools(host: ToolHost): void;

package/dist/tools/secrets-captcha-tools.js

@@ -0,0 +1,231 @@
+import { resolveCaptchaProvider, submitToProvider, unconfiguredFailure, } from "../page/solve-captcha.js";
+import { applyCredentialToRegistry } from "../util/credentials.js";
+import { estimateTokens } from "../util/tokens.js";
+import { SESSION_ARG } from "./schemas.js";
+/** Stamp a captcha result body with its token estimate and wrap it as a tool
+ *  text response — the shared shape every solve_captcha envelope uses. */
+function captchaJsonResult(body) {
+    const withTokens = { ...body, tokensEstimate: estimateTokens(JSON.stringify(body)) };
+    return { content: [{ type: "text", text: JSON.stringify(withTokens, null, 2) }] };
+}
+/** Read the widget site-key from a selector — `data-sitekey` (the
+ *  reCAPTCHA/hCaptcha/Turnstile convention) first, then common alternatives.
+ *  Returns undefined when the selector misses or carries no key. */
+async function readSiteKeyFromSelector(page, selector) {
+    try {
+        const handle = await page.$(selector);
+        if (!handle)
+            return undefined;
+        const key = (await handle.getAttribute("data-sitekey")) ??
+            (await handle.getAttribute("data-site-key")) ??
+            (await handle.getAttribute("sitekey")) ??
+            undefined;
+        await handle.dispose().catch(() => undefined);
+        return key;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Secrets / captcha / credentials tools — the off-by-default egress-sensitive
+ * seams: `register_secret` (the per-session secrets registry that backs egress
+ * masking), `solve_captcha` (the provider-bridge), and `get_totp` /
+ * `get_credential` (the credentials provider). Registered through the shared
+ * `ToolHost` seam.
+ */
+export function registerSecretsCaptchaTools(host) {
+    const { z, register, gateCheck, entryFor, caps, credentialsResolved } = host;
+    // ---------- secrets registry (capability `secrets`) ----------
+    register("register_secret", {
+        capability: "secrets",
+        description: 'Register a sensitive value the agent will use without ever seeing the real string in any tool result. **Gated behind the off-by-default `secrets` capability** — same posture class as `eval` / `network-body` / `disableWebSecurity`. Pair: the agent calls `fill({value:"<NAME>"})` / `press({key:"<NAME>"})` and the runtime substitutes the registered real value AT dispatch (so the page receives the actual string), while EVERY egress sink — `ActionResult.network`, `network_read`, `network_body`, `ws_read`, `console_read`, `snapshot`, `find` evidence — strips occurrences of the real value back to `<NAME>` before returning to the agent. `name` must match `/^[A-Z][A-Z0-9_]*$/` (uppercase identifier — the `<NAME>` mask is the stable contract). Optional `scope` (URL substring, case-insensitive) narrows the *dispatch* side: a scoped secret won\'t be substituted into a `fill` whose page URL doesn\'t contain the scope (refuses with a clear error). Per-session registry, capped at 32 entries. `screenshot` is a PARTIAL sink: when the page\'s text content contains a registered value, a warning is appended; pixel-level redaction (region-blur) is deferred — call snapshot/find for verified-clean evidence instead. NEVER re-emits or logs the real value.',
+        inputSchema: {
+            name: z
+                .string()
+                .describe('Agent-facing alias, e.g. "PASSWORD" / "OTP" / "SESSION_TOKEN". Uppercase identifier — `<NAME>` mask format.'),
+            value: z
+                .string()
+                .describe("The real secret value. Stored per-session in memory only; never persisted, never logged."),
+            scope: z
+                .string()
+                .optional()
+                .describe("Optional URL substring (case-insensitive). When set, dispatch-side substitution refuses if the current page URL doesn't contain the scope (prevents cross-origin leak). Egress masking is global regardless."),
+            ...SESSION_ARG,
+        },
+    }, async ({ name, value, scope, session, }) => {
+        const g = gateCheck("register_secret");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            e.secrets.register({ name, value, ...(scope ? { scope } : {}) });
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+        const body = {
+            ok: true,
+            registered: name,
+            scope: scope ?? null,
+            // never echo the value back. Echo only the registered names — useful
+            // for the agent to confirm what aliases are live without leaking.
+            names: e.secrets.names(),
+            tokensEstimate: estimateTokens(JSON.stringify({ ok: true, registered: name, scope, names: e.secrets.names() })),
+        };
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+    // ---------- captcha solver delegation (capability `captcha`) ----------
+    //
+    // `solve_captcha` is a delegation seam — it POSTs the captcha challenge to a
+    // provider configured per-deployment via environment variables
+    // (BROWX_CAPTCHA_PROVIDER + BROWX_CAPTCHA_API_KEY, optional
+    // BROWX_CAPTCHA_API_BASE / BROWX_CAPTCHA_TIMEOUT_MS / BROWX_CAPTCHA_POLL_MS).
+    // browxai does NOT bundle a solver and does NOT auto-purchase credits — when
+    // the capability is on but no provider is configured the tool returns a
+    // structured failure with a clear "no provider configured" hint. Loud-warned
+    // at boot (see the `captcha` warning above). Targets the 2Captcha-
+    // compatible HTTP API for v0.2.0 (`/in.php` submit + `/res.php` poll);
+    // CapMonster Cloud mirrors the same shape. Other providers can be added by
+    // extending src/page/solve-captcha.ts.
+    register("solve_captcha", {
+        capability: "captcha",
+        description: "Delegate a captcha challenge to a configured external provider (2Captcha / CapMonster / etc — provider speaks the 2Captcha-compatible REST API). **Gated behind the off-by-default `captcha` capability** — same posture class as `eval` / `network-body` / `secrets` / `extensions` / `stealth`. SOLVING CAPTCHAS MAY VIOLATE THE TARGET SITE'S TERMS OF SERVICE; the operator carries the legal exposure. " +
+            "Provider config is per-deployment via environment variables: BROWX_CAPTCHA_PROVIDER (`2captcha` or `capmonster`) + BROWX_CAPTCHA_API_KEY; optional BROWX_CAPTCHA_API_BASE / BROWX_CAPTCHA_TIMEOUT_MS / BROWX_CAPTCHA_POLL_MS. **browxai does NOT bundle a solver and does NOT auto-purchase credits** — when the capability is on but no provider is configured the tool returns a structured `ok:false` with a clear `no provider configured` hint. " +
+            "For widget captchas (`recaptcha2`, `recaptcha3`, `hcaptcha`, `turnstile`), supply the page's site-key via `siteKey` OR `selector` (when given, the server reads `data-sitekey` from the selected element on the current page). For `image`, supply `imageBase64` (raw base64, no data URL prefix). Returns `{ok, provider, solution, taskId, elapsedMs}` on success — the agent then types `solution` into the hidden form field / invokes the page's recaptcha callback. We do NOT auto-submit the solution; how to wire it into the page is per-site.",
+        inputSchema: {
+            type: z
+                .enum(["recaptcha2", "recaptcha3", "hcaptcha", "turnstile", "image"])
+                .describe("Captcha kind. `recaptcha2` = checkbox or invisible v2; `recaptcha3` = score-based v3; `hcaptcha` = hCaptcha widget; `turnstile` = Cloudflare Turnstile; `image` = base64 image upload (caller provides `imageBase64`)."),
+            selector: z
+                .string()
+                .optional()
+                .describe("CSS selector for the captcha widget element on the current page. When given, the server reads `data-sitekey` (or equivalent) from the element to populate `siteKey`. Either `selector` or `siteKey` is required for widget captchas."),
+            siteKey: z
+                .string()
+                .optional()
+                .describe("Explicit site-key for the captcha widget (alternative to `selector`). Required for widget captchas when `selector` is not given."),
+            imageBase64: z
+                .string()
+                .optional()
+                .describe("Raw base64-encoded image bytes (no `data:image/...;base64,` prefix). Required for `image` type; ignored for widget types."),
+            ...SESSION_ARG,
+        },
+    }, async ({ type, selector, siteKey, imageBase64, session, }) => {
+        const g = gateCheck("solve_captcha");
+        if (g)
+            return g;
+        // Resolve provider config fresh per call so an operator can rotate creds
+        // via env without restarting (env is the source of truth).
+        const cfg = resolveCaptchaProvider(process.env);
+        if (!cfg.ok) {
+            if (cfg.reason === "unconfigured")
+                return captchaJsonResult(unconfiguredFailure());
+            return captchaJsonResult({
+                ok: false,
+                provider: null,
+                error: cfg.error ?? "captcha provider config is incomplete",
+                hint: "Set BROWX_CAPTCHA_PROVIDER and BROWX_CAPTCHA_API_KEY together. browxai does NOT bundle a solver and does NOT auto-purchase credits.",
+            });
+        }
+        const e = await entryFor(session);
+        let pageUrl;
+        try {
+            pageUrl = e.session.page().url();
+        }
+        catch {
+            return captchaJsonResult({
+                ok: false,
+                provider: cfg.config.provider,
+                error: "session has no active page",
+                hint: "Call open_session + navigate first.",
+            });
+        }
+        // Resolve siteKey: explicit > selector-derived. For `image` neither is
+        // needed (imageBase64 is the payload).
+        let resolvedSiteKey = siteKey;
+        if (!resolvedSiteKey && selector && type !== "image") {
+            resolvedSiteKey = await readSiteKeyFromSelector(e.session.page(), selector);
+            if (!resolvedSiteKey) {
+                return captchaJsonResult({
+                    ok: false,
+                    provider: cfg.config.provider,
+                    error: `solve_captcha: could not read a site-key attribute from selector "${selector}"`,
+                    hint: "Pass `siteKey` explicitly, or pass a `selector` that points at an element carrying `data-sitekey` (the standard reCAPTCHA / hCaptcha / Turnstile widget attribute).",
+                });
+            }
+        }
+        const result = await submitToProvider({
+            type,
+            pageUrl,
+            ...(resolvedSiteKey ? { siteKey: resolvedSiteKey } : {}),
+            ...(imageBase64 ? { imageBase64 } : {}),
+        }, cfg.config);
+        // Mask the solution through the per-session secrets registry so a
+        // solver-issued token containing a registered value (unlikely but
+        // defensible) doesn't bypass the egress layer.
+        const masked = e.secrets.applyMaskDeep(result);
+        const body = { ...masked, tokensEstimate: estimateTokens(JSON.stringify(masked)) };
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+    // ---------- credentials hook (capability `credentials`) ----------
+    //
+    // Pluggable TOTP / username+password lookup against an operator-configured
+    // vault. Off-by-default; loud-warned at boot. Provider is per-deployment,
+    // NEVER bundled. `get_credential` ADDITIONALLY requires the `secrets`
+    // capability (auto-registers the looked-up password into the secrets-mask
+    // registry under `<PASSWORD_<account>>` — without `secrets`, the lookup
+    // refuses rather than leak cleartext into the result).
+    register("get_totp", {
+        capability: "credentials",
+        description: "Look up a one-time TOTP code from the deployment's configured credentials vault. **Gated behind the off-by-default `credentials` capability** — same posture class as `eval` / `network-body` / `secrets`. Provider is selected per-deployment via `BROWX_CREDENTIALS_PROVIDER` (`oathtool` default — no paid dependency, seeds via env or file; or `1password` / `bitwarden` / `lastpass` via their respective CLIs the operator installs out-of-band). Returns `{ok, code, provider}` on success; `{ok:false, error, hint, provider}` on failure (missing seed / CLI not on PATH / CLI not logged in — actionable hint included). TOTP codes are NOT masked through the secrets registry: a TOTP is single-use and short-lived, so masking buys little while complicating verify-step flows — the code is returned in plaintext so the agent can pass it to `fill({value: code})` or compare against on-page text. `account` semantics depend on the provider (oathtool: a key from `BROWX_OATHTOOL_SEEDS`; 1password/bitwarden/lastpass: an item name / id the CLI accepts).",
+        inputSchema: {
+            account: z
+                .string()
+                .describe("Provider-specific account identifier (oathtool seed key / 1password item name / bitwarden item id / lastpass item name)."),
+        },
+    }, async ({ account }) => {
+        const g = gateCheck("get_totp");
+        if (g)
+            return g;
+        const result = await credentialsResolved.provider.getTotp(account);
+        const body = {
+            ...result,
+            tokensEstimate: estimateTokens(JSON.stringify(result)),
+        };
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+    register("get_credential", {
+        capability: "credentials",
+        description: 'Look up a `{username, password}` pair from the deployment\'s configured credentials vault. **Gated behind the off-by-default `credentials` capability** AND additionally requires the `secrets` capability (without it the lookup refuses — returning a password in cleartext would leak it into the transcript on first reference). On success, the password is AUTO-REGISTERED into the per-session secrets registry under `<PASSWORD_<account>>` (account name sanitised to `/^[A-Z][A-Z0-9_]*$/`); the agent then passes `fill({value: "<PASSWORD_acct>"})` and the runtime materialises the real value AT Playwright dispatch. The returned object carries `{ok, username, aliasName, provider}` — **never the cleartext password**. Pair with `get_totp` for the 2FA half. `oathtool` provider does NOT support `get_credential` (TOTP-only) — pair with a credential-bearing provider. `account` semantics are provider-specific (1password: item name; bitwarden: item id; lastpass: item name).',
+        inputSchema: {
+            account: z
+                .string()
+                .describe("Provider-specific account identifier — see the per-provider notes in docs/tool-reference.md."),
+            ...SESSION_ARG,
+        },
+    }, async ({ account, session }) => {
+        const g = gateCheck("get_credential");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const raw = (await credentialsResolved.provider.getCredential(account));
+        // `applyCredentialToRegistry` enforces the `secrets`-capability
+        // pairing rule and strips `_password` before the result leaves this
+        // module — so the response we serialise never contains cleartext.
+        const registry = caps.enabled.has("secrets") ? e.secrets : null;
+        const result = applyCredentialToRegistry(raw, registry, account);
+        const body = {
+            ...result,
+            tokensEstimate: estimateTokens(JSON.stringify(result)),
+        };
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+}

package/dist/tools/session-dialog-permission-tools.d.ts

@@ -0,0 +1,9 @@
+import type { RegisterHost, GateHost, SessionHost, ConfigHost, ServerServicesHost } from "./host.js";
+/**
+ * Dialog / permission / file-system-picker policy tools: set_dialog_policy /
+ * set_permission_policy / set_fs_picker_policy / fs_picker_respond. Split out of
+ * `session-policy-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order. The host owns the
+ * closures (register / gate / entry / workspace).
+ */
+export declare function registerSessionDialogPermissionTools(host: RegisterHost & GateHost & SessionHost & ConfigHost & ServerServicesHost): void;