browxai 0.7.0

package/dist/session/registry.js

@@ -0,0 +1,98 @@
+// session registry. Holds one isolated SessionEntry per session id;
+// the "default" entry is created lazily on first browser-touching tool call
+// (back-compat: every existing caller that omits `session` resolves here).
+//
+// Browser-agnostic by construction: the registry takes an entry `factory` and
+// a `teardown`, so it's unit-testable without launching Chrome. The factory /
+// teardown that actually wire Playwright live in server.ts.
+export const DEFAULT_SESSION_ID = "default";
+export class SessionRegistry {
+    factory;
+    teardown;
+    entries = new Map();
+    /** In-flight creations, so two concurrent first-calls for the same id don't
+     *  each launch a browser. */
+    creating = new Map();
+    constructor(factory, teardown) {
+        this.factory = factory;
+        this.teardown = teardown;
+    }
+    /** Resolve (or lazily create) the entry for `id`. Concurrency-safe. The
+     *  `spec` is only consulted on creation — once an entry exists it's returned
+     *  as-is regardless of spec. */
+    async get(id = DEFAULT_SESSION_ID, spec) {
+        const existing = this.entries.get(id);
+        if (existing) {
+            existing.lastActivityAt = Date.now(); // touch for idle reaping
+            return existing;
+        }
+        const inflight = this.creating.get(id);
+        if (inflight)
+            return inflight;
+        const p = this.factory(id, spec)
+            .then((e) => {
+            this.entries.set(id, e);
+            this.creating.delete(id);
+            return e;
+        })
+            .catch((err) => {
+            this.creating.delete(id);
+            throw err;
+        });
+        this.creating.set(id, p);
+        return p;
+    }
+    has(id) {
+        return this.entries.has(id);
+    }
+    /** Non-creating peek — returns undefined if not yet open. */
+    peek(id) {
+        return this.entries.get(id);
+    }
+    list() {
+        return [...this.entries.values()];
+    }
+    /** Tear down + remove one session. Returns false if it wasn't open. */
+    async close(id) {
+        const e = this.entries.get(id);
+        if (!e)
+            return false;
+        this.entries.delete(id);
+        await this.teardown(e);
+        return true;
+    }
+    /**
+     * bulk teardown. Selects live sessions by `prefix` (id starts-with),
+     * `all`, and/or `idleMs` (no `get()` in the last N ms). Filters AND together
+     * when multiple are given; at least one selector is required. Returns the
+     * closed ids (in selection order). The team-lead reap primitive — at
+     * multi-agent scale a wedged/killed agent strands sessions.
+     */
+    async closeMatching(sel) {
+        const now = Date.now();
+        const victims = [...this.entries.values()].filter((e) => {
+            if (sel.prefix !== undefined && !e.id.startsWith(sel.prefix))
+                return false;
+            if (sel.idleMs !== undefined && now - e.lastActivityAt < sel.idleMs)
+                return false;
+            // `all` (or prefix/idle match with all unset) — if no positive selector
+            // was given the caller must pass `all`, enforced at the tool layer.
+            return true;
+        });
+        const closed = [];
+        for (const e of victims) {
+            this.entries.delete(e.id);
+            await this.teardown(e).catch(() => undefined);
+            closed.push(e.id);
+        }
+        return closed;
+    }
+    /** Tear down everything (server shutdown). */
+    async closeAll() {
+        const all = [...this.entries.values()];
+        this.entries.clear();
+        for (const e of all) {
+            await this.teardown(e).catch(() => undefined);
+        }
+    }
+}

package/dist/session/safari-post-wire.d.ts

@@ -0,0 +1,8 @@
+import type { SessionEntry } from "./registry.js";
+import type { PostWireDeps } from "../engine/registry.js";
+/** Attach Safari's BiDi console bridge to the entry's console buffer. Returns the
+ *  promise the session factory awaits (the BiDi `subscribe` is async). Takes the
+ *  per-server `PostWireDeps` to honour the standardized `postWire(entry, deps)`
+ *  contract, but ignores them: Safari attaches only its BiDi console bridge, none of
+ *  the Playwright caps/configStore/workspace-gated steps. */
+export declare function safariPostWire(entry: SessionEntry, _deps: PostWireDeps): Promise<void>;

package/dist/session/safari-post-wire.js

@@ -0,0 +1,28 @@
+// The Safari post-creation wiring (RFC 0004 D1 + D5). Safari attaches NOTHING
+// Playwright-bound — it has no Page, no CDP, no BrowserContext. Its only
+// post-creation step is the BiDi console bridge: Safari's console arrives over the
+// experimental WebDriver-BiDi `log.entryAdded` stream (when the cap negotiated),
+// not via a Playwright page. Subscribed here at session creation so load-time logs
+// are caught; strictly optional (when BiDi did not negotiate, the buffer stays
+// empty and `console_read` still works, returning nothing).
+//
+// This is the `else` leg of the old `if (sess.engine !== "safari")` console guard
+// in session-registry.ts:303-313 — relocated verbatim into the engine that owns
+// it, so the caller no longer branches on the engine name.
+/** Attach Safari's BiDi console bridge to the entry's console buffer. Returns the
+ *  promise the session factory awaits (the BiDi `subscribe` is async). Takes the
+ *  per-server `PostWireDeps` to honour the standardized `postWire(entry, deps)`
+ *  contract, but ignores them: Safari attaches only its BiDi console bridge, none of
+ *  the Playwright caps/configStore/workspace-gated steps. */
+export async function safariPostWire(entry, _deps) {
+    const handle = entry.session.safari?.();
+    if (handle?.bidi) {
+        const bidi = handle.bidi;
+        await bidi.subscribe(["log.entryAdded"]).catch(() => undefined);
+        bidi.on("log.entryAdded", (p) => {
+            const level = typeof p.level === "string" ? p.level : "info";
+            const text = typeof p.text === "string" ? p.text : "";
+            entry.console.ingest(level, text);
+        });
+    }
+}

package/dist/session/safari-session.d.ts

@@ -0,0 +1,10 @@
+import type { SafariSessionHandle } from "../engine/index.js";
+import type { BrowserSession } from "./types.js";
+/** The structured error `page()` throws on a Safari session — names why and where
+ *  to route instead. Exported so callers/tests assert on it consistently. */
+export declare const NO_PLAYWRIGHT_PAGE: string;
+/** Wrap a live Safari adapter handle as a `BrowserSession`. `page()` throws
+ *  (`NO_PLAYWRIGHT_PAGE`); `safari()` exposes the native handle; `close()` tears
+ *  the safaridriver session + process down. Managed/isolated only — Safari has no
+ *  headless and no separate-context incognito (incognito/byob refuse upstream). */
+export declare function buildSafariSession(handle: SafariSessionHandle): BrowserSession;

package/dist/session/safari-session.js

@@ -0,0 +1,39 @@
+// The Safari BrowserSession — the no-Playwright-Page seam. Safari
+// is the first engine with neither a Playwright Page nor CDP, so its session
+// wraps the adapter's Safari-native handle (WebDriver Classic + optional BiDi)
+// and makes `page()` a structured THROW rather than returning a fake Page. Tools
+// that can run on Safari route through `safari()` (the snapshot substrate reads
+// via the handle's execute/sync; click/fill/navigate/cookies via its WebDriver
+// Classic client); everything else is capability-gated up front, so `page()` is
+// never reached on a supported tool.
+//
+// Factored out of managed.ts so it unit-tests with a mock handle (no safaridriver
+// spawn) and so the page()-throw message has one home.
+/** The structured error `page()` throws on a Safari session — names why and where
+ *  to route instead. Exported so callers/tests assert on it consistently. */
+export const NO_PLAYWRIGHT_PAGE = "safari-no-playwright-page: the safari engine has no Playwright Page (it is driven over " +
+    "safaridriver, not Playwright). Tools that run on Safari route through the Safari-native handle " +
+    "(session.safari()) — snapshot/find via the substrate, navigate/click/fill/screenshot/cookies via " +
+    "its WebDriver Classic client; everything else is capability-gated.";
+/** Wrap a live Safari adapter handle as a `BrowserSession`. `page()` throws
+ *  (`NO_PLAYWRIGHT_PAGE`); `safari()` exposes the native handle; `close()` tears
+ *  the safaridriver session + process down. Managed/isolated only — Safari has no
+ *  headless and no separate-context incognito (incognito/byob refuse upstream). */
+export function buildSafariSession(handle) {
+    let closed = false;
+    return {
+        mode: "managed",
+        ownsBrowser: true,
+        engine: "safari",
+        page: () => {
+            throw new Error(NO_PLAYWRIGHT_PAGE);
+        },
+        safari: () => handle,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await handle.close();
+        },
+    };
+}

package/dist/session/storage.d.ts

@@ -0,0 +1,148 @@
+import type { BrowserContext, Page } from "playwright-core";
+/** Playwright's `storageState()` return shape (re-stated locally so callers
+ *  don't need to depend on playwright-core directly). */
+export interface StorageStateBlob {
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        expires: number;
+        httpOnly: boolean;
+        secure: boolean;
+        sameSite: "Strict" | "Lax" | "None";
+    }>;
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+/** Cookie shape Playwright accepts in `addCookies`. */
+export interface CookieInput {
+    name: string;
+    value: string;
+    /** Either `url` OR (`domain` + `path`) is required. */
+    url?: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+export declare function assertSafeName(kind: string, name: string): void;
+/** Resolve a workspace-rooted path. Rejects any path that escapes the root
+ *  (`..` segments, absolute paths pointing outside, etc.). Mirrors the
+ *  `upload_file` contract. */
+export declare function resolveWorkspacePath(workspaceRoot: string, p: string, tool: string): string;
+/** Dump the context's storage state. Optionally writes JSON to a
+ *  workspace-rooted path; ALWAYS returns the blob. */
+export declare function dumpStorageState(context: BrowserContext, workspaceRoot: string, opts?: {
+    path?: string;
+}): Promise<{
+    state: StorageStateBlob;
+    path?: string;
+    bytes?: number;
+}>;
+/** Read + validate a state blob from a workspace-rooted file path. */
+export declare function readStorageStateFile(workspaceRoot: string, p: string, tool: string): StorageStateBlob;
+/** 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 declare function injectStorageState(context: BrowserContext, page: Page, state: StorageStateBlob, opts?: {
+    mode?: "replace" | "merge";
+}): Promise<{
+    mode: "replace" | "merge";
+    cookiesApplied: number;
+    originsApplied: number;
+    originsSkipped: string[];
+}>;
+export declare function cookiesGet(context: BrowserContext, args: {
+    name: string;
+    url?: string;
+}): Promise<StorageStateBlob["cookies"][number] | null>;
+export declare function cookiesList(context: BrowserContext, args?: {
+    urls?: string[];
+}): Promise<StorageStateBlob["cookies"]>;
+export declare function cookiesSet(context: BrowserContext, args: CookieInput): Promise<{
+    ok: true;
+}>;
+export declare function cookiesDelete(context: BrowserContext, args: {
+    name: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+}): Promise<{
+    ok: true;
+}>;
+export declare function cookiesClear(context: BrowserContext): Promise<{
+    ok: true;
+}>;
+/** Storage kind — exact same JS surface, different storage object. */
+export type WebStorageKind = "localStorage" | "sessionStorage";
+export declare function webStorageGet(page: Page, kind: WebStorageKind, args: {
+    key: string;
+}, tool: string): Promise<{
+    value: string | null;
+    origin: string;
+}>;
+export declare function webStorageSet(page: Page, kind: WebStorageKind, args: {
+    key: string;
+    value: string;
+}, tool: string): Promise<{
+    ok: true;
+    origin: string;
+}>;
+export declare function webStorageList(page: Page, kind: WebStorageKind, tool: string): Promise<{
+    entries: Array<{
+        key: string;
+        value: string;
+    }>;
+    origin: string;
+}>;
+export declare function webStorageDelete(page: Page, kind: WebStorageKind, args: {
+    key: string;
+}, tool: string): Promise<{
+    ok: true;
+    origin: string;
+}>;
+export declare function webStorageClear(page: Page, kind: WebStorageKind, tool: string): Promise<{
+    ok: true;
+    origin: string;
+}>;
+/** Resolve the on-disk path for a named auth-state. Validates the name. */
+export declare function authStatePath(workspaceRoot: string, name: string): string;
+/** Capture the context's storage state into the named slot. Overwrites an
+ *  existing slot of the same name. */
+export declare function authSave(context: BrowserContext, workspaceRoot: string, name: string): Promise<{
+    ok: true;
+    name: string;
+    path: string;
+    bytes: number;
+    cookies: number;
+    origins: number;
+}>;
+/** Load a named auth-state from disk. Returns the parsed blob ready to feed
+ *  into `open_session({ storageState })` or `inject_storage_state`. */
+export declare function authLoad(workspaceRoot: string, name: string): StorageStateBlob;
+/** Enumerate every named state in the workspace. Read-only; returns
+ *  `{name, path, bytes, modifiedAt}` per slot. */
+export declare function authList(workspaceRoot: string): Array<{
+    name: string;
+    path: string;
+    bytes: number;
+    modifiedAt: string;
+}>;
+/** Delete a named state. Returns whether the slot existed. */
+export declare function authDelete(workspaceRoot: string, name: string): {
+    ok: true;
+    existed: boolean;
+    path: string;
+};