browxai 0.7.0

package/dist/session/storage.js

@@ -0,0 +1,350 @@
+// Three-layer storage-state primitives — .
+//
+// The deferred bulk-state ask, with the @playwright/mcp lesson baked
+// in: bulk alone isn't enough — adopters constantly need to read a single
+// cookie ("am I logged in?") or set one ("opt-out=1") without round-tripping
+// a full blob. So three layers ship together:
+//
+//   1. Bulk     — `dump_storage_state` / `inject_storage_state` (wraps
+//                  `BrowserContext.storageState()` / `setStorageState()`).
+//   2. Granular — cookies + localStorage + sessionStorage CRUD (cookies via
+//                  Playwright's `BrowserContext.addCookies`/`cookies`/
+//                  `clearCookies`; web-storage via `page.evaluate(...)` since
+//                  it's origin-scoped — the page MUST be navigated to the
+//                  target origin first).
+//   3. Named    — `auth_save({name})` / `auth_load({name})` wrap layer 1 with
+//                  workspace-rooted JSON files at
+//                  `$BROWX_WORKSPACE/.auth-states/<name>.json`. No parallel
+//                  implementation — they delegate to layer 1.
+//
+// Capability split (server.ts):
+//   - reads  (`*_get`, `*_list`, `dump_storage_state`)              → `read`
+//   - writes (`*_set`, `*_delete`, `*_clear`,
+//             `inject_storage_state`, `auth_save`, `auth_load`)     → `action`
+//
+// Workspace contract: every `path` arg resolves inside `$BROWX_WORKSPACE`;
+// path-traversal is rejected (same posture as `upload_file`). Named-state
+// names are restricted to a safe character set (no separators, no `..`).
+//
+// Secrets-masking interplay: cookie *values* may carry credentials. A
+// future secrets-masking pass will mask them on egress. For now the gap
+// is documented; no extra work here.
+import { resolve, sep, join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, rmSync, } from "node:fs";
+// ---- workspace path / name validators -------------------------------------
+/** Names for named-states + similar file-naming use. No path separators,
+ *  no leading dots, no `..`. Same posture as `profile-snapshot.ts`. */
+const SAFE_NAME = /^[A-Za-z0-9._-]+$/;
+export function assertSafeName(kind, name) {
+    if (!name || !SAFE_NAME.test(name) || name === "." || name === "..") {
+        throw new Error(`${kind} "${name}" invalid — use only letters, digits, '.', '_', '-' ` +
+            `(no path separators, no "..")`);
+    }
+}
+/** Resolve a workspace-rooted path. Rejects any path that escapes the root
+ *  (`..` segments, absolute paths pointing outside, etc.). Mirrors the
+ *  `upload_file` contract. */
+export function resolveWorkspacePath(workspaceRoot, p, tool) {
+    const resolved = resolve(workspaceRoot, p);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`${tool}: \`path\` must resolve inside $BROWX_WORKSPACE — got "${p}". ` +
+            `Use a workspace-relative path (or call \`auth_save\` for the named-state path).`);
+    }
+    return resolved;
+}
+// ---- layer 1: bulk --------------------------------------------------------
+/** Dump the context's storage state. Optionally writes JSON to a
+ *  workspace-rooted path; ALWAYS returns the blob. */
+export async function dumpStorageState(context, workspaceRoot, opts = {}) {
+    const state = await context.storageState();
+    if (opts.path === undefined)
+        return { state };
+    // `resolved` is workspace-rooted by construction — `resolveWorkspacePath`
+    // (above) rejects any path outside `workspace.root` / $BROWX_WORKSPACE.
+    const resolved = resolveWorkspacePath(workspaceRoot, opts.path, "dump_storage_state");
+    const json = JSON.stringify(state, null, 2);
+    // ensure parent dir exists — still under workspace.root by construction.
+    const parent = resolved.substring(0, Math.max(resolved.lastIndexOf(sep), 0));
+    if (parent && !existsSync(parent))
+        mkdirSync(parent, { recursive: true });
+    writeFileSync(resolved, json, "utf8");
+    return { state, path: resolved, bytes: Buffer.byteLength(json, "utf8") };
+}
+/** Read + validate a state blob from a workspace-rooted file path. */
+export function readStorageStateFile(workspaceRoot, p, tool) {
+    const resolved = resolveWorkspacePath(workspaceRoot, p, tool);
+    if (!existsSync(resolved)) {
+        throw new Error(`${tool}: storage-state file not found at "${resolved}"`);
+    }
+    const raw = readFileSync(resolved, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${tool}: storage-state file "${resolved}" is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    validateStorageStateShape(parsed, tool);
+    return parsed;
+}
+function validateStorageStateShape(value, tool) {
+    if (!value || typeof value !== "object") {
+        throw new Error(`${tool}: storage-state must be an object with \`cookies\` and \`origins\` arrays`);
+    }
+    const v = value;
+    if (!Array.isArray(v.cookies)) {
+        throw new Error(`${tool}: storage-state.\`cookies\` must be an array`);
+    }
+    if (!Array.isArray(v.origins)) {
+        throw new Error(`${tool}: storage-state.\`origins\` must be an array`);
+    }
+}
+/** Inject a storage-state into an EXISTING context. Two modes:
+ *    - `replace` (default) — wipes the context's cookies/localStorage/IndexedDB
+ *      and applies the new state. Uses Playwright's `setStorageState`.
+ *    - `merge`  — adds cookies via `addCookies` without clearing; localStorage
+ *      merge requires a navigation to each origin and runs via `page.evaluate`
+ *      (best-effort: only the currently-loaded page's origin is updated; other
+ *      origins in the blob are skipped with a note in the result). */
+export async function injectStorageState(context, page, state, opts = {}) {
+    const mode = opts.mode ?? "replace";
+    if (mode === "replace") {
+        // setStorageState clears existing cookies + localStorage + IndexedDB first.
+        await context.setStorageState(state);
+        return {
+            mode,
+            cookiesApplied: state.cookies.length,
+            originsApplied: state.origins.length,
+            originsSkipped: [],
+        };
+    }
+    // merge: cookies are safe to add without clearing.
+    if (state.cookies.length)
+        await context.addCookies(state.cookies);
+    let originsApplied = 0;
+    const originsSkipped = [];
+    const currentOrigin = (() => {
+        try {
+            return new URL(page.url()).origin;
+        }
+        catch {
+            return null;
+        }
+    })();
+    for (const o of state.origins) {
+        if (currentOrigin === o.origin) {
+            await page.evaluate((entries) => {
+                for (const e of entries)
+                    window.localStorage.setItem(e.name, e.value);
+            }, o.localStorage);
+            originsApplied += 1;
+        }
+        else {
+            originsSkipped.push(o.origin);
+        }
+    }
+    return { mode, cookiesApplied: state.cookies.length, originsApplied, originsSkipped };
+}
+// ---- layer 2: cookies CRUD ------------------------------------------------
+export async function cookiesGet(context, args) {
+    if (!args.name)
+        throw new Error("cookies_get: `name` is required");
+    const list = await context.cookies(args.url ? [args.url] : undefined);
+    return list.find((c) => c.name === args.name) ?? null;
+}
+export async function cookiesList(context, args = {}) {
+    const list = await context.cookies(args.urls);
+    return list;
+}
+export async function cookiesSet(context, args) {
+    if (!args.name)
+        throw new Error("cookies_set: `name` is required");
+    if (typeof args.value !== "string")
+        throw new Error("cookies_set: `value` (string) is required");
+    if (!args.url && !(args.domain && args.path)) {
+        throw new Error("cookies_set: pass either `url` (recommended) OR both `domain` and `path` — " +
+            "Playwright's addCookies requires one of those two forms");
+    }
+    await context.addCookies([args]);
+    return { ok: true };
+}
+/** The cookie `path` Playwright assigns when `addCookies` is given a `url`:
+ *  the parent directory of the url path ("/storage" → "/", "/a/b" → "/a/").
+ *  Used so `cookies_delete` filters by the same path the URL-form
+ *  `cookies_set` stored under. */
+function urlCookiePath(pathname) {
+    return pathname.substring(0, pathname.lastIndexOf("/") + 1) || "/";
+}
+export async function cookiesDelete(context, args) {
+    if (!args.name)
+        throw new Error("cookies_delete: `name` is required");
+    // `clearCookies` accepts a filter — name + (optional) url / domain / path.
+    const filter = { name: args.name };
+    if (args.domain)
+        filter.domain = args.domain;
+    if (args.path)
+        filter.path = args.path;
+    if (args.url) {
+        try {
+            const u = new URL(args.url);
+            filter.domain = filter.domain ?? u.hostname;
+            // Match Playwright's URL→cookie-path rule (the parent "directory" of the
+            // url path), so a delete by the SAME url that `cookies_set` used actually
+            // matches: addCookies({url}) stores e.g. "/storage" at path "/", so a
+            // delete filter of the raw pathname "/storage" would match nothing.
+            filter.path = filter.path ?? urlCookiePath(u.pathname);
+        }
+        catch {
+            throw new Error(`cookies_delete: invalid url "${args.url}"`);
+        }
+    }
+    await context.clearCookies(filter);
+    return { ok: true };
+}
+export async function cookiesClear(context) {
+    await context.clearCookies();
+    return { ok: true };
+}
+/** localStorage/sessionStorage are origin-scoped and tied to the current
+ *  page; we must drive them via `page.evaluate`. The page MUST be navigated
+ *  to the target origin first — on `about:blank` or a different origin the
+ *  call throws a Playwright SecurityError, which we re-frame with a clearer
+ *  hint. */
+function webStorageGuard(page, kind, tool) {
+    let url;
+    try {
+        url = page.url();
+    }
+    catch {
+        url = "";
+    }
+    if (!url || url === "about:blank") {
+        throw new Error(`${tool}: ${kind} is origin-scoped and the page is at "${url || "(unknown)"}". ` +
+            `Navigate the session to the target origin first.`);
+    }
+}
+// Browser-side storage references — string form to avoid pulling the DOM
+// lib into tsconfig. Mirrors `src/page/shortcut.ts`. The `kind` parameter is
+// the literal `localStorage` or `sessionStorage` member name on `window`.
+export async function webStorageGet(page, kind, args, tool) {
+    if (!args.key)
+        throw new Error(`${tool}: \`key\` is required`);
+    webStorageGuard(page, kind, tool);
+    const expr = `(() => { var s = window.${kind}; ` +
+        `return { value: s.getItem(${JSON.stringify(args.key)}), origin: window.location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+export async function webStorageSet(page, kind, args, tool) {
+    if (!args.key)
+        throw new Error(`${tool}: \`key\` is required`);
+    if (typeof args.value !== "string")
+        throw new Error(`${tool}: \`value\` (string) is required`);
+    webStorageGuard(page, kind, tool);
+    const expr = `(() => { var s = window.${kind}; ` +
+        `s.setItem(${JSON.stringify(args.key)}, ${JSON.stringify(args.value)}); ` +
+        `return { ok: true, origin: window.location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+export async function webStorageList(page, kind, tool) {
+    webStorageGuard(page, kind, tool);
+    const expr = `(() => { var s = window.${kind}; var out = []; ` +
+        `for (var i = 0; i < s.length; i++) { var k = s.key(i); if (k === null) continue; ` +
+        `out.push({ key: k, value: s.getItem(k) || "" }); } ` +
+        `return { entries: out, origin: window.location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+export async function webStorageDelete(page, kind, args, tool) {
+    if (!args.key)
+        throw new Error(`${tool}: \`key\` is required`);
+    webStorageGuard(page, kind, tool);
+    const expr = `(() => { var s = window.${kind}; s.removeItem(${JSON.stringify(args.key)}); ` +
+        `return { ok: true, origin: window.location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+export async function webStorageClear(page, kind, tool) {
+    webStorageGuard(page, kind, tool);
+    const expr = `(() => { var s = window.${kind}; s.clear(); ` +
+        `return { ok: true, origin: window.location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+// ---- layer 3: named auth-states -------------------------------------------
+const AUTH_STATES_DIR = ".auth-states";
+/** Resolve the on-disk path for a named auth-state. Validates the name. */
+export function authStatePath(workspaceRoot, name) {
+    assertSafeName("auth state name", name);
+    return join(workspaceRoot, AUTH_STATES_DIR, `${name}.json`);
+}
+/** Capture the context's storage state into the named slot. Overwrites an
+ *  existing slot of the same name. */
+export async function authSave(context, workspaceRoot, name) {
+    // `dest` + `dir` below are rooted at `workspaceRoot` ($BROWX_WORKSPACE) by
+    // construction — `authStatePath` validates the name through `assertSafeName`
+    // (no separators / no traversal) before joining under workspaceRoot.
+    const dest = authStatePath(workspaceRoot, name);
+    const dir = join(workspaceRoot, AUTH_STATES_DIR);
+    // workspace.root-rooted by construction (see comment above).
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const state = await context.storageState();
+    const json = JSON.stringify(state, null, 2);
+    // workspace.root-rooted by construction (see comment above).
+    writeFileSync(dest, json, "utf8");
+    return {
+        ok: true,
+        name,
+        path: dest,
+        bytes: Buffer.byteLength(json, "utf8"),
+        cookies: state.cookies.length,
+        origins: state.origins.length,
+    };
+}
+/** Load a named auth-state from disk. Returns the parsed blob ready to feed
+ *  into `open_session({ storageState })` or `inject_storage_state`. */
+export function authLoad(workspaceRoot, name) {
+    const path = authStatePath(workspaceRoot, name);
+    if (!existsSync(path)) {
+        throw new Error(`auth_load: no named state "${name}" — call auth_save({ name }) first (looked for ${path})`);
+    }
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`auth_load: named state "${name}" is corrupt JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    validateStorageStateShape(parsed, "auth_load");
+    return parsed;
+}
+/** Enumerate every named state in the workspace. Read-only; returns
+ *  `{name, path, bytes, modifiedAt}` per slot. */
+export function authList(workspaceRoot) {
+    const dir = join(workspaceRoot, AUTH_STATES_DIR);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const name = entry.slice(0, -".json".length);
+        if (!SAFE_NAME.test(name))
+            continue;
+        const path = join(dir, entry);
+        try {
+            const st = statSync(path);
+            out.push({ name, path, bytes: st.size, modifiedAt: new Date(st.mtimeMs).toISOString() });
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Delete a named state. Returns whether the slot existed. */
+export function authDelete(workspaceRoot, name) {
+    const path = authStatePath(workspaceRoot, name);
+    const existed = existsSync(path);
+    if (existed)
+        rmSync(path, { force: true });
+    return { ok: true, existed, path };
+}

package/dist/session/types.d.ts

@@ -0,0 +1,113 @@
+import type { Browser, BrowserContext, CDPSession, Page } from "playwright-core";
+import type { EngineKind, SafariSessionHandle } from "../engine/index.js";
+export type SessionMode = "managed" | "byob";
+/** resolved device/viewport emulation options applied at context
+ *  creation. A subset of Playwright's context options — enough for
+ *  responsive / touch / DPR testing without re-exposing the whole API. */
+export interface DeviceConfig {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    userAgent?: string;
+}
+export interface SessionOptions {
+    headless?: boolean;
+    /** BYOB only: `http://127.0.0.1:9222` etc. Loopback enforced. */
+    attachCdp?: string;
+    /** Workspace-rooted profile dir (managed only). */
+    profileDir?: string;
+    /** device/viewport emulation, applied at context creation. */
+    device?: DeviceConfig;
+    /** launch with `--disable-web-security --disable-site-isolation-trials`
+     *  (SOP/CORS OFF browser-wide). managed/incognito only; loud-warned. */
+    disableWebSecurity?: boolean;
+    /** Seed the new context's storage state at creation. Honoured by
+     *  **incognito** mode (where `browser.newContext({storageState})` is the
+     *  native primitive). For **persistent** (managed) mode the context's
+     *  state is on disk in the profile dir — the storageState is applied
+     *  post-create via `context.setStorageState`, which CLEARS the profile's
+     *  existing cookies / localStorage first. For BYOB/attached the value is
+     *  ignored (not-owned: we don't mutate the consumer's Chrome). */
+    storageState?: import("./storage.js").StorageStateBlob;
+    /** Enable HAR recording at context creation via Playwright's native
+     *  `recordHar` context option. Honoured by managed + incognito (we own the
+     *  context); ignored on BYOB/attached (not-owned). The HAR is finalized by
+     *  Playwright when the context closes. The path is workspace-rooted by
+     *  construction (resolved upstream). */
+    recordHar?: {
+        path: string;
+        mode?: "full" | "minimal";
+        content?: "embed" | "attach" | "omit";
+        urlFilter?: string | RegExp;
+    };
+    /** Enable video recording at context creation via Playwright's native
+     *  `recordVideo` context option. Honoured by managed + incognito (we own
+     *  the context); ignored on BYOB/attached (not-owned). The .webm is
+     *  finalized by Playwright when the context closes — the registry's
+     *  teardown calls `page.video().saveAs(targetPath)` for a deterministic
+     *  output filename. The `dir` is workspace-rooted by construction
+     *  (resolved upstream — Playwright auto-names the file inside). */
+    recordVideo?: {
+        dir: string;
+        size?: {
+            width: number;
+            height: number;
+        };
+    };
+    /** Absolute filesystem paths to unpacked Chromium extension directories
+     *  (each containing `manifest.json`). Honoured by **persistent (managed)**
+     *  launches in **headed** mode only — chromium's `--load-extension` +
+     *  `--disable-extensions-except` flags are emitted from this list. Empty /
+     *  unset → no extension flags. Path safety (workspace-rooted) is enforced
+     *  at the tool layer (`extensions_install`); this option is the trusted
+     *  internal pipe. Refused on incognito / attached at the tool layer. */
+    extensionPaths?: readonly string[];
+    /** Which browser engine to launch. Defaults to `"chromium"` everywhere — the
+     *  default makes every launch byte-identical to the pre-seam behavior.
+     *  chromium, firefox, webkit, and android are all implemented (each via its
+     *  adapter); a future-declared engine without an adapter throws
+     *  `engine-not-yet-supported` at the launch path (see src/engine/). `android`
+     *  is attach-only (real Chrome-on-Android over adb + CDP) — managed/ephemeral
+     *  launch refuses with `android-launch-not-supported`. */
+    browserType?: EngineKind;
+    /** The launch mode the EngineRegistry's `makeAdapter` builds for. The three
+     *  session factories (managed / incognito / byob) thread this through so the
+     *  per-engine launch/attach branching collapses into one registry lookup —
+     *  the factory keeps the MODE concern (option-building), the engine entry owns
+     *  the per-engine launch. Defaults to `"managed"` (a bare `makeAdapter(opts)`
+     *  with no `launchMode` is the managed launch, matching the 0004-03 §1 safari
+     *  example). Internal: never set from the wire — `open_session` carries
+     *  `mode`, which the factory maps to this. */
+    launchMode?: "managed" | "incognito" | "byob";
+}
+export interface BrowserSession {
+    readonly mode: SessionMode;
+    readonly ownsBrowser: boolean;
+    /** The engine backing this session. Always `"chromium"` today. */
+    readonly engine: EngineKind;
+    page(): Page;
+    /** Raw CDP handle. Optional: present + fully functional on chromium (the only
+     *  engine wired today), absent on engines without a CDP escape hatch. This is
+     *  the one mandatory interface member that used to hard-gate multi-engine.
+     *  Consumers that need the handle route through `requireCdp()` (src/engine/),
+     *  which asserts presence with a structured, engine-naming error. */
+    cdp?(): CDPSession;
+    /** The Safari-native handle — present ONLY on the `safari` engine, the first
+     *  engine with no Playwright `Page`. On a Safari session,
+     *  `page()` THROWS (`safari-no-playwright-page`); consumers that can run on
+     *  Safari (snapshot/find/navigate/screenshot/cookies via this handle's
+     *  WebDriver Classic + BiDi clients) route through `safari()` instead, and the
+     *  capability gate refuses the rest up front. Absent on every other engine. */
+    safari?(): SafariSessionHandle;
+    close(): Promise<void>;
+}
+export interface SessionInternals {
+    browser?: Browser;
+    context: BrowserContext;
+    page: Page;
+    cdp: CDPSession;
+}

package/dist/session/types.js

@@ -0,0 +1,5 @@
+// BrowserSession is the lifecycle abstraction the rest of the server uses.
+// Two implementations: managed.ts (we launch the browser, we own its lifecycle)
+// and byob.ts (we attach to an externally-launched Chrome via CDP; not-owned —
+// no close, no storage reset on shutdown).
+export {};

package/dist/session/wedge.d.ts

@@ -0,0 +1,15 @@
+export declare const WEDGE_THRESHOLD = 3;
+export declare class WedgeTracker {
+    private consecutive;
+    /** A call against this session hit the anti-wedge deadline. */
+    recordTimeout(): void;
+    /** A call against this session returned responsively (a success, or a fast
+     *  non-timeout error). The session answered — clear the streak. */
+    recordResponsive(): void;
+    /** Consecutive anti-wedge timeouts seen so far. */
+    get count(): number;
+    /** True once the session has timed out WEDGE_THRESHOLD times in a row. */
+    wedged(): boolean;
+    /** Agent-facing recovery hint for a wedged session. */
+    hint(): string;
+}

package/dist/session/wedge.js

@@ -0,0 +1,41 @@
+// Per-session wedge detector.
+//
+// The anti-wedge deadline (see util/deadline.ts) makes every individual call
+// return within its budget — but an agent driving a wedged session sees only
+// a stream of separate `ok:false` timeouts and must *infer* that the whole
+// session is dead. In practice agents miss that inference and retry the dead
+// session for a long time. This converts the inference into a server-provided
+// signal: after WEDGE_THRESHOLD consecutive anti-wedge deadline-timeouts on a
+// session, results carry `sessionWedged: true` + a discard-and-reopen hint.
+// Any responsive call (a success, or a fast non-timeout error) clears the
+// streak — a responsive call proves the session is still alive.
+export const WEDGE_THRESHOLD = 3;
+export class WedgeTracker {
+    consecutive = 0;
+    /** A call against this session hit the anti-wedge deadline. */
+    recordTimeout() {
+        this.consecutive += 1;
+    }
+    /** A call against this session returned responsively (a success, or a fast
+     *  non-timeout error). The session answered — clear the streak. */
+    recordResponsive() {
+        this.consecutive = 0;
+    }
+    /** Consecutive anti-wedge timeouts seen so far. */
+    get count() {
+        return this.consecutive;
+    }
+    /** True once the session has timed out WEDGE_THRESHOLD times in a row. */
+    wedged() {
+        return this.consecutive >= WEDGE_THRESHOLD;
+    }
+    /** Agent-facing recovery hint for a wedged session. */
+    hint() {
+        return (`${this.consecutive} consecutive anti-wedge timeouts on this session — ` +
+            `it is wedged. STOP retrying it: raising \`timeoutMs\` or re-navigating ` +
+            `in place will NOT recover a wedged session. Discard it with ` +
+            `\`close_session\`, then \`open_session\` (or any call on a fresh id) ` +
+            `to get a clean session. Page state in the wedged session is lost — ` +
+            `restart that work in the new session.`);
+    }
+}

package/dist/tools/action-core-tools.d.ts

@@ -0,0 +1,13 @@
+import { type ActionToolHost } from "./action-tool.js";
+import type { ConfigHost, ServerServicesHost } from "./host.js";
+/**
+ * Core action verbs: navigate / click / fill / press / shortcut. Split out of
+ * `action-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered through
+ * the shared `ToolHost` seam in the same source order. `click` and `fill` are the
+ * canonical confirm-gated target-resolving handlers, so they ride the `actionTool`
+ * wrapper (RFC 0004 P3 / D4) — byte-identical to the prior hand-written body.
+ * navigate (confirmNavigation), press (optional target), and shortcut (try/catch
+ * over runShortcut) keep their own bodies — their shapes differ from the canonical
+ * pipeline.
+ */
+export declare function registerActionCoreTools(host: ActionToolHost & ConfigHost & ServerServicesHost): void;