@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/browser/extension/session.js

@@ -0,0 +1,321 @@
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+const escaped = (value) => value.replace(/[&<>]/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[char]);
+const quote = (value) => JSON.stringify(value.slice(0, 240));
+const ACTIONABLE = new Set(['button', 'link', 'textbox', 'combobox', 'checkbox', 'radio', 'menuitem', 'tab', 'switch', 'option']);
+export class BraveBrowserSession {
+    options;
+    tabs = new Map();
+    current = null;
+    queue = Promise.resolve();
+    idle = null;
+    idleMs;
+    downloads = [];
+    profileNote = 'Brave is using your existing profile. Only normal tabs on sites you allowed in the extension are available; Incognito tabs are never exposed.';
+    constructor(options) {
+        this.options = options;
+        this.idleMs = options.idleMs;
+    }
+    run(work) {
+        const next = this.queue.then(work, work);
+        this.queue = next.catch(() => undefined);
+        this.touch();
+        return next;
+    }
+    touch() {
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.idle = setTimeout(this.options.onIdle, this.idleMs);
+        this.idle.unref?.();
+    }
+    async invoke(operation) {
+        const response = await this.options.bridge.request(operation);
+        if (!isRecord(response) || typeof response.ok !== 'boolean')
+            throw new Error('The Brave extension returned an invalid response.');
+        if (!response.ok)
+            throw new Error(typeof response.error === 'string' ? response.error : 'The Brave extension could not complete the operation.');
+        return response.value;
+    }
+    idFor(tabId) {
+        return `b${tabId.toString(36)}`;
+    }
+    async refreshTabs() {
+        const remote = await this.invoke({ op: 'tabs.list' });
+        if (!Array.isArray(remote))
+            throw new Error('The Brave extension returned an invalid tab list.');
+        const live = new Set();
+        this.current = null;
+        for (const entry of remote) {
+            if (!isRecord(entry) || !Number.isInteger(entry.tabId) || typeof entry.url !== 'string' || typeof entry.title !== 'string' || !Number.isInteger(entry.generation))
+                continue;
+            if (await this.options.network.refusal(entry.url))
+                continue;
+            const tabId = Number(entry.tabId);
+            const id = this.idFor(tabId);
+            live.add(id);
+            const old = this.tabs.get(id);
+            if (old) {
+                old.remote = { tabId, url: entry.url, title: entry.title, generation: Number(entry.generation), active: entry.active === true };
+                old.generation = Number(entry.generation);
+            }
+            else {
+                this.tabs.set(id, {
+                    id,
+                    remote: { tabId, url: entry.url, title: entry.title, generation: Number(entry.generation), active: entry.active === true },
+                    generation: Number(entry.generation), refs: new Map(), refsGeneration: -1,
+                    page: new BravePage(this, id)
+                });
+            }
+            if (entry.active === true)
+                this.current = id;
+        }
+        for (const id of this.tabs.keys())
+            if (!live.has(id))
+                this.tabs.delete(id);
+        if (this.current && !this.tabs.has(this.current))
+            this.current = null;
+    }
+    async refresh() {
+        await this.refreshTabs();
+    }
+    async refreshOne(id) {
+        await this.refreshTabs();
+        const tab = this.tabs.get(id);
+        if (!tab)
+            throw new Error(`Brave tab ${id} is no longer available. The tab may have closed, or the page may have moved to a site you have not allowed.`);
+        return tab;
+    }
+    get(id) {
+        const tab = this.tabs.get(id);
+        if (!tab)
+            throw new Error(`There is no tab ${id}. browser_tabs lists the available tabs.`);
+        return tab;
+    }
+    async tab(id) {
+        await this.refreshTabs();
+        if (id) {
+            const tab = this.tabs.get(id);
+            if (!tab)
+                throw new Error(`There is no tab ${id}. browser_tabs lists the available tabs.`);
+            return tab;
+        }
+        if (this.current && this.tabs.has(this.current))
+            return this.tabs.get(this.current);
+        return this.open();
+    }
+    async open() {
+        const tabId = await this.invoke({ op: 'tabs.create' });
+        if (!Number.isInteger(tabId))
+            throw new Error('The Brave extension did not return the new tab.');
+        await this.refreshTabs();
+        const tab = this.tabs.get(this.idFor(tabId));
+        if (!tab)
+            throw new Error('Brave created a tab but it is not available yet. Try browser_tabs again.');
+        this.current = tab.id;
+        return tab;
+    }
+    async select(id) {
+        const tab = this.get(id);
+        await this.invoke({ op: 'tabs.activate', tabId: tab.remote.tabId });
+        this.current = id;
+        await this.refreshTabs();
+        return this.get(id);
+    }
+    list() {
+        return [...this.tabs.entries()].map(([id, tab]) => ({ id, url: tab.remote.url, current: id === this.current }));
+    }
+    get network() {
+        return this.options.network;
+    }
+    get started() {
+        return true;
+    }
+    async close() {
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.tabs.clear();
+        this.current = null;
+    }
+}
+class BravePage {
+    session;
+    id;
+    refs = new Map();
+    constructor(session, id) {
+        this.session = session;
+        this.id = id;
+    }
+    get tab() {
+        return this.session.get(this.id);
+    }
+    async refresh() {
+        const tab = await this.session.refreshOne(this.id);
+        tab.generation = tab.remote.generation;
+    }
+    url() {
+        return this.tab.remote.url;
+    }
+    async title() {
+        await this.refresh();
+        return this.tab.remote.title;
+    }
+    async goto(url) {
+        await this.session.invoke({ op: 'page.navigate', tabId: this.tab.remote.tabId, url });
+        await this.refresh();
+        return null;
+    }
+    async goBack() {
+        await this.session.invoke({ op: 'page.back', tabId: this.tab.remote.tabId });
+        await this.refresh();
+        return null;
+    }
+    async goForward() {
+        await this.session.invoke({ op: 'page.forward', tabId: this.tab.remote.tabId });
+        await this.refresh();
+        return null;
+    }
+    async reload() {
+        await this.session.invoke({ op: 'page.reload', tabId: this.tab.remote.tabId });
+        await this.refresh();
+        return null;
+    }
+    async close() {
+        await this.session.invoke({ op: 'tabs.close', tabId: this.tab.remote.tabId });
+    }
+    async ariaSnapshot(options = { mode: 'ai' }) {
+        const response = await this.session.invoke({
+            op: 'page.snapshot', tabId: this.tab.remote.tabId,
+            ...(options.depth ? { depth: Math.max(1, Math.min(40, options.depth)) } : {})
+        });
+        const tab = this.tab;
+        tab.generation = response.generation;
+        tab.remote.generation = response.generation;
+        this.refs.clear();
+        const nodes = Array.isArray(response.nodes) ? response.nodes : [];
+        const byId = new Map(nodes.filter(node => node && typeof node.nodeId === 'string').map(node => [node.nodeId, node]));
+        const lines = [];
+        let nextRef = 1;
+        const walk = (node, depth) => {
+            if (depth > (options.depth ?? 12))
+                return;
+            const role = node.role || 'text';
+            const name = node.name?.trim() ?? '';
+            const actionable = ACTIONABLE.has(role) && Number.isInteger(node.backendDOMNodeId);
+            if (!node.ignored && role !== 'rootWebArea' && role !== 'none' && (name || actionable)) {
+                const ref = actionable ? `e${nextRef++}` : null;
+                if (ref)
+                    this.refs.set(ref, { backendDOMNodeId: node.backendDOMNodeId, generation: response.generation });
+                const suffix = ref ? ` [ref=${ref}]` : '';
+                const level = role === 'heading' && Number.isInteger(node.level) ? ` [level=${node.level}]` : '';
+                lines.push(`${'  '.repeat(depth)}- ${role}${name ? ` ${quote(name)}` : ''}${level}${suffix}`);
+            }
+            for (const childId of node.childIds ?? []) {
+                const child = byId.get(childId);
+                if (child)
+                    walk(child, depth + 1);
+            }
+        };
+        const roots = nodes.filter(node => !node.parentId || !byId.has(node.parentId));
+        for (const root of roots)
+            walk(root, 0);
+        return lines.join('\n');
+    }
+    async content() {
+        await this.refresh();
+        const value = await this.session.invoke({ op: 'page.text', tabId: this.tab.remote.tabId });
+        this.tab.remote.title = value.title;
+        return `<html><head><title>${escaped(value.title)}</title></head><body>${escaped(value.text)}</body></html>`;
+    }
+    async screenshot(options) {
+        return this.capture(options);
+    }
+    getByRef(ref) {
+        const target = this.refs.get(ref);
+        if (!target)
+            throw new Error(`There is no live element for ref ${ref}. Take browser_snapshot again.`);
+        return new BraveLocator(this, target);
+    }
+    async evaluate(expression) {
+        await this.refresh();
+        return this.session.invoke({ op: 'page.evaluate', tabId: this.tab.remote.tabId, expression });
+    }
+    keyboard = {
+        press: async (key) => {
+            await this.session.invoke({ op: 'page.press', tabId: this.tab.remote.tabId, key });
+        }
+    };
+    mouse = {
+        wheel: async (x, y) => {
+            await this.session.invoke({ op: 'page.scroll', tabId: this.tab.remote.tabId, x, y });
+        }
+    };
+    async waitForTimeout(ms) {
+        await new Promise(resolve => setTimeout(resolve, Math.min(10_000, Math.max(0, ms))));
+    }
+    getByText(text) {
+        return { first: () => ({ waitFor: async ({ timeout }) => {
+                    const end = Date.now() + timeout;
+                    while (Date.now() < end) {
+                        const found = await this.session.invoke({ op: 'page.containsText', tabId: this.tab.remote.tabId, text });
+                        if (found)
+                            return;
+                        await new Promise(resolve => setTimeout(resolve, 250));
+                    }
+                    const error = new Error(`Timeout ${timeout}ms exceeded while waiting for text`);
+                    error.name = 'TimeoutError';
+                    throw error;
+                } }) };
+    }
+    getNode(target) {
+        if (target.generation !== this.tab.generation || this.tab.refsGeneration !== this.tab.generation)
+            throw new Error(`The page in ${this.id} changed since its last snapshot. Take browser_snapshot again and use a ref from it.`);
+        return target.backendDOMNodeId;
+    }
+    async locatorCall(target, method, args = {}) {
+        await this.refresh();
+        const backendDOMNodeId = this.getNode(target);
+        return this.session.invoke({ op: 'page.element', tabId: this.tab.remote.tabId, backendDOMNodeId, generation: target.generation, method, ...args });
+    }
+    async capture(options, target) {
+        await this.refresh();
+        const args = { op: 'page.screenshot', tabId: this.tab.remote.tabId, quality: Math.max(10, Math.min(95, options.quality)) };
+        if (target) {
+            args.backendDOMNodeId = this.getNode(target);
+            args.generation = target.generation;
+        }
+        const result = await this.session.invoke(args);
+        return Buffer.from(result.data, 'base64');
+    }
+}
+class BraveLocator {
+    page;
+    target;
+    constructor(page, target) {
+        this.page = page;
+        this.target = target;
+    }
+    async click(options = {}) {
+        await this.page.locatorCall({ ...this.target }, 'click', { button: options.button ?? 'left', double: false });
+    }
+    async dblclick(options = {}) {
+        await this.page.locatorCall({ ...this.target }, 'click', { button: options.button ?? 'left', double: true });
+    }
+    async screenshot(options) {
+        return this.page.capture(options, this.target);
+    }
+    async evaluate(callback) {
+        const declaration = callback.toString();
+        return this.page.locatorCall({ ...this.target }, 'evaluate', { functionDeclaration: `function(){ return (${declaration})(this) }` });
+    }
+    async fill(value) {
+        await this.page.locatorCall({ ...this.target }, 'fill', { text: value });
+    }
+    async press(key) {
+        await this.page.locatorCall({ ...this.target }, 'press', { key });
+    }
+    async selectOption(values) {
+        return this.page.locatorCall({ ...this.target }, 'select', { values });
+    }
+    async scrollIntoViewIfNeeded() {
+        await this.page.locatorCall({ ...this.target }, 'scrollIntoView');
+    }
+}

package/dist/sdk/browser/index.d.ts

@@ -0,0 +1,33 @@
+import type { PluginDescriptor } from "../plugins/types.js";
+import type { WorldContext, WorldPart } from "../world/world.js";
+import type { ToolSpec } from "../tools/types.js";
+import { NetworkPolicy } from "./network.js";
+import { type Launcher } from "./session.js";
+import type { BrowserToolSession } from "./tools.js";
+import { BrowserExtensionBridge } from "./extension/bridge.js";
+export declare const BROWSER_PLUGIN: PluginDescriptor;
+/** A browser closes after this long without a call. */
+export declare const IDLE_MS: number;
+export interface BrowserPartOptions {
+    stateDir: string;
+    launch?: Launcher;
+    /** Replaces the address check in tests. */
+    network?: NetworkPolicy;
+    idleMs?: number;
+    extensionPort?: number;
+}
+/** Foundation-owned isolated browser engine. Plugin tools receive sessions through this interface. */
+export interface BrowserEngine {
+    sessions: Map<string, BrowserToolSession>;
+    extension: BrowserExtensionBridge;
+    diagnostics: NonNullable<WorldPart['diagnostics']>;
+    tools(context: WorldContext): ToolSpec[];
+    toolsForSession(session: import("../tools/types.js").ToolSession, context: WorldContext): ToolSpec[];
+    release(sessionKey: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createBrowserEngine(options: BrowserPartOptions): BrowserEngine;
+/** Plugin adapter that exposes the Foundation engine's checked browser tools to a session. */
+export declare function browserPluginPart(engine: BrowserEngine): WorldPart;
+/** Combined adapter retained for direct browser tests and embedders that construct a WorldPart. */
+export declare function browserPart(options: BrowserPartOptions): WorldPart & Pick<BrowserEngine, 'sessions' | 'release' | 'close'>;

package/dist/sdk/browser/index.js

@@ -0,0 +1,105 @@
+// Foundation owns the isolated browser engine; the Browser plugin exposes its user-facing tools.
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { readBrowserConfig } from "./config.js";
+import { browserDiagnostic } from "./diagnostics.js";
+import { NetworkPolicy } from "./network.js";
+import { BrowserSession, fileName, launchBrowser } from "./session.js";
+import { BrowserExtensionBridge } from "./extension/bridge.js";
+import { BraveBrowserSession } from "./extension/session.js";
+import { BROWSER_TOOL_NAMES, browserTools } from "./tools.js";
+export const BROWSER_PLUGIN = {
+    id: 'browser',
+    title: 'Browser',
+    description: 'The browser backend selected by the person: an isolated Harness profile or the connected Brave profile. Brave exposes only normal tabs on sites explicitly allowed in the extension, never Incognito; a disconnect refuses calls and never switches backends. Sending, buying, deleting, account changes and granting access always ask you.',
+    manage: 'tools',
+    switchable: { on: true },
+    // Its tools are listed in the World group, which the Web plugin owns.
+    tools: BROWSER_TOOL_NAMES.map((name) => ({ name }))
+};
+/** A browser closes after this long without a call. */
+export const IDLE_MS = 15 * 60_000;
+export function createBrowserEngine(options) {
+    const sessions = new Map();
+    const owners = new Map();
+    const diagnosticKeys = new Set();
+    const config = () => readBrowserConfig(options.stateDir);
+    const network = options.network ?? new NetworkPolicy(config);
+    const extension = new BrowserExtensionBridge({ stateDir: options.stateDir, port: options.extensionPort });
+    const releaseExact = async (key) => {
+        const session = sessions.get(key);
+        sessions.delete(key);
+        owners.delete(key);
+        await session?.close();
+        if (diagnosticKeys.delete(key))
+            rmSync(join(options.stateDir, 'browser', 'downloads', fileName(key)), { recursive: true, force: true });
+    };
+    const sessionFor = (context, backend) => {
+        const key = `${backend}:${context.sessionKey}`;
+        let session = sessions.get(key);
+        if (!session) {
+            owners.set(key, context.sessionKey);
+            if (context.caller.surface === 'doctor') {
+                diagnosticKeys.add(key);
+                session = new BrowserSession({
+                    key,
+                    profileDir: null,
+                    downloadsDir: join(options.stateDir, 'browser', 'downloads', fileName(key)),
+                    config: () => ({ ...config(), backend: 'isolated', cdpUrl: null, headed: false }),
+                    network,
+                    launch: options.launch ?? launchBrowser,
+                    idleMs: options.idleMs ?? IDLE_MS,
+                    onIdle: () => void releaseExact(key)
+                });
+            }
+            else if (backend === 'brave') {
+                session = new BraveBrowserSession({ bridge: extension, network, idleMs: options.idleMs ?? IDLE_MS, onIdle: () => void releaseExact(key) });
+            }
+            else {
+                const owner = context.caller.agentId ?? context.caller.projectId ?? 'default';
+                session = new BrowserSession({
+                    key,
+                    profileDir: join(options.stateDir, 'browser', 'profiles', fileName(owner)),
+                    downloadsDir: join(options.stateDir, 'browser', 'downloads', fileName(key)),
+                    config,
+                    network,
+                    launch: options.launch ?? launchBrowser,
+                    idleMs: options.idleMs ?? IDLE_MS,
+                    onIdle: () => void releaseExact(key)
+                });
+            }
+            sessions.set(key, session);
+        }
+        return session;
+    };
+    const toolsForContext = (context) => {
+        const backend = context.caller.surface !== 'doctor' && config().backend === 'brave' ? 'brave' : 'isolated';
+        const session = sessionFor(context, backend);
+        return browserTools(context, () => session);
+    };
+    const release = async (sessionKey) => {
+        const keys = [...owners.entries()].filter(([, owner]) => owner === sessionKey).map(([key]) => key);
+        await Promise.all(keys.map(releaseExact));
+    };
+    return {
+        diagnostics: () => [browserDiagnostic(config)],
+        sessions,
+        extension,
+        tools: toolsForContext,
+        toolsForSession: (_session, context) => toolsForContext(context),
+        release,
+        close: async () => {
+            await Promise.all([...sessions.keys()].map(releaseExact));
+            await extension.close();
+        }
+    };
+}
+/** Plugin adapter that exposes the Foundation engine's checked browser tools to a session. */
+export function browserPluginPart(engine) {
+    return { plugin: BROWSER_PLUGIN, diagnostics: engine.diagnostics, tools: context => engine.tools(context) };
+}
+/** Combined adapter retained for direct browser tests and embedders that construct a WorldPart. */
+export function browserPart(options) {
+    const engine = createBrowserEngine(options);
+    return { ...browserPluginPart(engine), sessions: engine.sessions, release: engine.release, close: engine.close };
+}

package/dist/sdk/browser/network.d.ts

@@ -0,0 +1,10 @@
+import type { BrowserConfig } from "./config.js";
+export declare class NetworkPolicy {
+    private readonly config;
+    private readonly resolve;
+    private readonly hosts;
+    constructor(config: () => BrowserConfig, resolve?: (host: string) => Promise<string[]>);
+    /** Why an address may not be loaded, or null when it may. */
+    refusal(address: string): Promise<string | null>;
+    private isPublic;
+}

package/dist/sdk/browser/network.js

@@ -0,0 +1,59 @@
+// What a page in the harness's browser may reach. The same rule as `web_fetch`: public addresses
+// only, unless a person allowed private ones for local development. This filters the browser's
+// requests; it is a guard, not a sandbox (a page's own DNS can still differ from ours).
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { isPublicAddress } from "../web/safeRequest.js";
+const OPEN_SCHEMES = new Set(['data:', 'blob:', 'about:']);
+const CACHE_MS = 60_000;
+export class NetworkPolicy {
+    config;
+    resolve;
+    hosts = new Map();
+    constructor(config, resolve = async (host) => (await lookup(host, { all: true, verbatim: true })).map((entry) => entry.address)) {
+        this.config = config;
+        this.resolve = resolve;
+    }
+    /** Why an address may not be loaded, or null when it may. */
+    async refusal(address) {
+        let url;
+        try {
+            url = new URL(address);
+        }
+        catch {
+            return 'That is not a web address.';
+        }
+        if (OPEN_SCHEMES.has(url.protocol))
+            return null;
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return `${url.protocol} addresses cannot be opened.`;
+        if (url.username || url.password)
+            return 'Addresses with a username or password cannot be opened.';
+        const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        const { allowedDomains, allowPrivate } = this.config();
+        if (allowedDomains.length && !allowedDomains.some((domain) => host === domain || host.endsWith(`.${domain}`)))
+            return `${host} is not among the sites this browser may reach.`;
+        if (allowPrivate)
+            return null;
+        return (await this.isPublic(host)) ? null : `${host} is not a public address. A person can allow private addresses in the browser settings.`;
+    }
+    async isPublic(host) {
+        if (isIP(host))
+            return isPublicAddress(host);
+        if (host === 'localhost' || host.endsWith('.localhost'))
+            return false;
+        const cached = this.hosts.get(host);
+        if (cached && Date.now() - cached.at < CACHE_MS)
+            return cached.ok;
+        let ok = false;
+        try {
+            const addresses = await this.resolve(host);
+            ok = addresses.length > 0 && addresses.every(isPublicAddress);
+        }
+        catch {
+            ok = false;
+        }
+        this.hosts.set(host, { at: Date.now(), ok });
+        return ok;
+    }
+}

package/dist/sdk/browser/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function browserServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/browser/serverMethods.js

@@ -0,0 +1,10 @@
+import { pick } from "../server/params.js";
+export function browserServerMethods(harness) {
+    return {
+        'browser.config': () => harness.world.browserConfig(),
+        'browser.configure': (params) => harness.world.configureBrowser(pick(params, ['backend', 'headed', 'cdpUrl', 'executablePath', 'allowPrivate', 'allowedDomains'])),
+        'browser.extension.status': () => harness.world.browserExtensionStatus(),
+        'browser.extension.start': () => harness.world.browserExtensionStart(),
+        'browser.extension.stop': () => harness.world.browserExtensionStop()
+    };
+}

package/dist/sdk/browser/session.d.ts

@@ -0,0 +1,85 @@
+import type { Browser, BrowserContext, Page } from 'playwright-core';
+import type { BrowserConfig } from "./config.js";
+import type { NetworkPolicy } from "./network.js";
+/** Any name as a file or folder name: other characters become `_`. */
+export declare const fileName: (name: string) => string;
+export declare const VIEWPORT: {
+    width: number;
+    height: number;
+};
+export declare const ACTION_TIMEOUT_MS = 15000;
+export declare const NAVIGATION_TIMEOUT_MS = 30000;
+export interface Tab {
+    id: string;
+    page: Page;
+    /** Bumped on every navigation of the tab's main frame: refs of an earlier generation are stale. */
+    generation: number;
+    /** Refs of the latest snapshot, with the snapshot line that names each. */
+    refs: Map<string, string>;
+    refsGeneration: number;
+}
+export interface Download {
+    tab: string;
+    path: string;
+    name: string;
+}
+/** Opens a browser context; tests replace it. */
+export type Launcher = (input: {
+    profileDir: string | null;
+    downloads: string;
+    config: BrowserConfig;
+}) => Promise<{
+    context: BrowserContext;
+    browser: Browser | null;
+    attached: boolean;
+}>;
+export declare const launchBrowser: Launcher;
+export interface BrowserSessionOptions {
+    key: string;
+    /** The profile kept for this caller, or null for a throwaway one. */
+    profileDir: string | null;
+    downloadsDir: string;
+    config: () => BrowserConfig;
+    network: NetworkPolicy;
+    launch: Launcher;
+    idleMs: number;
+    onIdle: () => void;
+}
+export declare class BrowserSession {
+    private readonly options;
+    private closed;
+    private context;
+    private browser;
+    private attached;
+    private starting;
+    private readonly tabs;
+    private current;
+    private nextTab;
+    private queue;
+    private idle;
+    private temporaryProfile;
+    readonly downloads: Download[];
+    /** Set when the kept profile was in use and a throwaway one was opened instead. */
+    profileNote: string | null;
+    constructor(options: BrowserSessionOptions);
+    /** Runs `work` after every earlier call of this session has finished. */
+    run<T>(work: () => Promise<T>): Promise<T>;
+    private touch;
+    private start;
+    private adopt;
+    private forget;
+    /** A tab by id, or the current one, starting the browser and opening a first tab when needed. */
+    tab(id?: string | null): Promise<Tab>;
+    open(): Promise<Tab>;
+    select(id: string): Tab;
+    list(): {
+        id: string;
+        url: string;
+        current: boolean;
+    }[];
+    /** What pages in this browser may reach. */
+    get network(): NetworkPolicy;
+    get currentId(): string | null;
+    get started(): boolean;
+    close(): Promise<void>;
+}