@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/accounts/store.js

@@ -0,0 +1,255 @@
+// Accounts. One profile (settings, registry, memory) and any number of Pi accounts, each with
+// its own isolated agent folder, stored credentials, sign-in state, limits, health, and audit
+// trail.
+//
+// Device-local layout under `<state dir>/accounts/`:
+//   accounts.json        accounts, the default, pools (no secrets)
+//   <id>/state.json      health, plan, limits, last error (no secrets)
+//   <id>/home/pi/        Pi's own agent folder for this account
+//   _shared/pi/          settings, skills, prompts linked into every account's agent folder
+//   audit.jsonl          append-only account actions (secrets scrubbed)
+//
+// Switching is always manual. A pool only chooses an account when a session starts; a running
+// or resumed session keeps the account it started with.
+import { mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { appendLine, newId, now, readJsonOr, safeId, writeJson } from "../core/fs.js";
+import { charCount, compareText, lines, takeChars } from "../core/text.js";
+/** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
+export const PROVIDER = 'pi';
+export const emptyState = () => ({ health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] });
+// ---- Files ------------------------------------------------------------------------------
+const registryPath = (dir) => join(dir, 'accounts.json');
+const statePath = (dir, accountId) => join(dir, safeId(accountId), 'state.json');
+export function loadRegistry(dir) {
+    const stored = readJsonOr(registryPath(dir), {}) ?? {};
+    return { accounts: stored.accounts ?? [], defaults: stored.defaults ?? {}, pools: stored.pools ?? [], migratedProviderKeys: stored.migratedProviderKeys ?? false };
+}
+export function saveRegistry(dir, registry) {
+    mkdirSync(dir, { recursive: true });
+    writeJson(registryPath(dir), registry);
+}
+export function loadState(dir, accountId) {
+    try {
+        return { ...emptyState(), ...(readJsonOr(statePath(dir, accountId), {}) ?? {}) };
+    }
+    catch {
+        return emptyState();
+    }
+}
+function saveState(dir, accountId, state) {
+    writeJson(statePath(dir, accountId), state);
+}
+/** Replaces anything that looks like a token so audit lines and stored errors never hold secrets. */
+export function scrub(text) {
+    const words = text.split(' ').map((word) => {
+        const bytes = Buffer.byteLength(word);
+        const tokenLike = bytes >= 24 && (word.match(/[A-Za-z0-9]/g)?.length ?? 0) * 10 >= bytes * 8;
+        return tokenLike || word.startsWith('sk-') || word.startsWith('sess-') ? '[redacted]' : word;
+    });
+    return takeChars(words.join(' '), 500);
+}
+export function audit(dir, accountId, action, detail) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        appendLine(join(dir, 'audit.jsonl'), JSON.stringify({ at: now(), accountId, action, detail: scrub(detail) }));
+    }
+    catch {
+        // An audit line that cannot be written never fails the action it describes.
+    }
+}
+/** The newest audit entries first, optionally for one account. */
+export function readAudit(dir, accountId, limit = 100) {
+    let text = '';
+    try {
+        text = readFileSync(join(dir, 'audit.jsonl'), 'utf8');
+    }
+    catch {
+        text = '';
+    }
+    const entries = lines(text).flatMap((line) => {
+        try {
+            const entry = JSON.parse(line);
+            return entry && typeof entry.at === 'string' && typeof entry.action === 'string' && (!accountId || entry.accountId === accountId) ? [entry] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+    return entries.reverse().slice(0, Math.min(limit, 1000));
+}
+// ---- Health -----------------------------------------------------------------------------
+function inFuture(timestamp) {
+    const time = timestamp ? Date.parse(timestamp) : Number.NaN;
+    return !Number.isNaN(time) && time > Date.now();
+}
+// How long a limit error that came without a reset time keeps the account limited. Providers
+// report no limit windows, so nothing else would ever lift it.
+const UNTIMED_LIMIT_ERROR_SECS = 3600;
+export const isLimitCategory = (category) => category === 'rate_limited' || category === 'quota';
+/**
+ * Whether a `rate_limited` or `quota` error still counts. With a reset time it counts until
+ * then; without one it counts for a short while after it was recorded.
+ */
+export function limitErrorActive(issue) {
+    if (issue.resetsAt)
+        return inFuture(issue.resetsAt);
+    const at = Date.parse(issue.at);
+    return !Number.isNaN(at) && Math.trunc((Date.now() - at) / 1000) < UNTIMED_LIMIT_ERROR_SECS;
+}
+export function deriveHealth(state) {
+    const limitedByWindow = state.limits.some((limit) => (limit.status === 'rejected' || (limit.usedPercent ?? 0) >= 100) && (!limit.resetsAt || inFuture(limit.resetsAt)));
+    const issue = state.lastError;
+    if (issue?.category === 'auth_expired')
+        return 'auth_expired';
+    if (issue && isLimitCategory(issue.category) && limitErrorActive(issue))
+        return 'limited';
+    if (state.signedIn === false)
+        return 'signed_out';
+    if (limitedByWindow)
+        return 'limited';
+    if (issue && !isLimitCategory(issue.category))
+        return 'error';
+    return state.signedIn === true ? 'ok' : 'unknown';
+}
+/** Read-modify-write on one account's state. Returns the previous health and the new state. */
+export function updateState(dir, accountId, change) {
+    const state = loadState(dir, accountId);
+    const previous = state.health;
+    change(state);
+    state.health = deriveHealth(state);
+    saveState(dir, accountId, state);
+    return { previous, state };
+}
+// ---- Lookup and pinning -----------------------------------------------------------------
+export function find(dir, accountId) {
+    const account = loadRegistry(dir).accounts.find((entry) => entry.id === accountId);
+    if (!account)
+        throw new HarnessError('account_required', "This session's account was removed.", 'Choose another account for it.');
+    return account;
+}
+const usable = (state) => state.health === 'ok' || state.health === 'unknown';
+/**
+ * Chooses the account for a new session: the explicit account, else the pool's first usable
+ * account, else the default, else the first account. It never skips to another one silently.
+ */
+export function resolve(dir, accountId, poolId) {
+    const registry = loadRegistry(dir);
+    if (accountId) {
+        const account = find(dir, accountId);
+        if (account.provider !== PROVIDER)
+            throw invalid('That account belongs to another provider.');
+        return account;
+    }
+    if (poolId) {
+        const pool = registry.pools.find((entry) => entry.id === poolId);
+        if (!pool)
+            throw notFound('Pool');
+        const members = pool.accountIds.flatMap((id) => registry.accounts.find((account) => account.id === id) ?? []);
+        const ready = members.find((account) => usable(loadState(dir, account.id)));
+        if (ready)
+            return ready;
+        const resets = members.flatMap((account) => {
+            const state = loadState(dir, account.id);
+            return [...state.limits.map((limit) => limit.resetsAt), state.lastError?.resetsAt].filter((reset) => Boolean(reset));
+        });
+        const earliest = resets.sort(compareText)[0];
+        throw new HarnessError('account_unavailable', `Every account in ${pool.label} is unavailable.`, earliest ? `The earliest reset is ${earliest}.` : 'Reauthenticate an account in Accounts.');
+    }
+    const account = registry.accounts.find((entry) => entry.id === registry.defaults[PROVIDER]) ?? registry.accounts.find((entry) => entry.provider === PROVIDER);
+    if (!account)
+        throw new HarnessError('account_required', 'Add a Pi account first.', 'Open Accounts (⌘4) to sign in.');
+    return account;
+}
+/** The default account, if any exists. */
+export function defaultAccount(dir) {
+    try {
+        return resolve(dir);
+    }
+    catch {
+        return null;
+    }
+}
+export function summaryAuthentication(dir) {
+    const states = loadRegistry(dir).accounts.filter((account) => account.provider === PROVIDER).map((account) => loadState(dir, account.id));
+    if (states.some((state) => state.signedIn === true))
+        return 'authenticated';
+    return states.some((state) => state.signedIn === false) ? 'unauthenticated' : 'unknown';
+}
+export function overview(dir) {
+    const registry = loadRegistry(dir);
+    return {
+        accounts: registry.accounts.filter((account) => account.provider === PROVIDER).map((account) => ({ ...account, isDefault: registry.defaults[account.provider] === account.id, state: loadState(dir, account.id) })),
+        pools: registry.pools.filter((pool) => pool.provider === PROVIDER),
+        defaults: registry.defaults
+    };
+}
+// ---- Changes ----------------------------------------------------------------------------
+export function cleanLabel(label) {
+    const cleaned = label.trim();
+    if (!cleaned || charCount(cleaned) > 60)
+        throw invalid('Give the account a name of 1–60 characters.');
+    return cleaned;
+}
+export function addAccount(dir, label, authKind) {
+    if (authKind !== 'subscription' && authKind !== 'apiKey')
+        throw invalid('Unknown sign-in type.');
+    const account = { id: newId(), provider: PROVIDER, label: cleanLabel(label), authKind, credentialStore: 'keyring', createdAt: now() };
+    const registry = loadRegistry(dir);
+    registry.defaults[PROVIDER] ??= account.id;
+    registry.accounts.push(account);
+    saveRegistry(dir, registry);
+    return account;
+}
+export function renameAccount(dir, accountId, label) {
+    const cleaned = cleanLabel(label);
+    const registry = loadRegistry(dir);
+    const account = registry.accounts.find((entry) => entry.id === accountId);
+    if (!account)
+        throw notFound('Account');
+    account.label = cleaned;
+    saveRegistry(dir, registry);
+}
+export function setDefault(dir, accountId) {
+    const account = find(dir, accountId);
+    const registry = loadRegistry(dir);
+    registry.defaults[account.provider] = account.id;
+    saveRegistry(dir, registry);
+    return account;
+}
+/** Drops the account from the registry, its pools, and the default. Its folder and secrets are the caller's to remove. */
+export function forgetAccount(dir, account) {
+    const registry = loadRegistry(dir);
+    registry.accounts = registry.accounts.filter((entry) => entry.id !== account.id);
+    if (registry.defaults[account.provider] === account.id) {
+        const next = registry.accounts.find((entry) => entry.provider === account.provider);
+        if (next)
+            registry.defaults[account.provider] = next.id;
+        else
+            delete registry.defaults[account.provider];
+    }
+    for (const pool of registry.pools)
+        pool.accountIds = pool.accountIds.filter((id) => id !== account.id);
+    saveRegistry(dir, registry);
+}
+export function savePool(dir, pool) {
+    const label = cleanLabel(pool.label);
+    const registry = loadRegistry(dir);
+    for (const id of pool.accountIds) {
+        const account = registry.accounts.find((entry) => entry.id === id);
+        if (!account)
+            throw notFound('Account');
+        if (account.provider !== PROVIDER)
+            throw invalid('A pool holds accounts of one provider.');
+    }
+    const next = { id: pool.id ? safeId(pool.id) : newId(), provider: PROVIDER, label, accountIds: [...pool.accountIds] };
+    registry.pools = [...registry.pools.filter((existing) => existing.id !== next.id), next];
+    saveRegistry(dir, registry);
+    return next;
+}
+export function removePool(dir, poolId) {
+    const registry = loadRegistry(dir);
+    registry.pools = registry.pools.filter((pool) => pool.id !== poolId);
+    saveRegistry(dir, registry);
+}

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

@@ -0,0 +1,16 @@
+export interface BrowserConfig {
+    /** Show the browser window instead of running it headless. */
+    headed: boolean;
+    /** Attach to a browser a person already runs (its DevTools address) instead of launching one. */
+    cdpUrl: string | null;
+    /** A browser program to launch; otherwise Chrome, then Edge, then Playwright's Chromium. */
+    executablePath: string | null;
+    /** Let pages reach this machine and private networks (local development servers). */
+    allowPrivate: boolean;
+    /** When set, pages may only reach these sites (and their subdomains). */
+    allowedDomains: string[];
+}
+export declare const DEFAULT_BROWSER_CONFIG: BrowserConfig;
+export declare const configPath: (stateDir: string) => string;
+export declare function readBrowserConfig(stateDir: string): BrowserConfig;
+export declare function writeBrowserConfig(stateDir: string, change: Partial<BrowserConfig>): BrowserConfig;

package/dist/sdk/browser/config.js

@@ -0,0 +1,22 @@
+// How the harness's browser runs, kept on this device: `<state dir>/browser.json`. Only a person
+// (through a command or the application) writes it; no tool argument can point the browser at
+// another endpoint or profile.
+import { join } from 'node:path';
+import { readJsonOr, writeJson } from "../core/fs.js";
+export const DEFAULT_BROWSER_CONFIG = { headed: false, cdpUrl: null, executablePath: null, allowPrivate: false, allowedDomains: [] };
+export const configPath = (stateDir) => join(stateDir, 'browser.json');
+export function readBrowserConfig(stateDir) {
+    const saved = readJsonOr(configPath(stateDir), {});
+    return {
+        headed: saved.headed === true,
+        cdpUrl: typeof saved.cdpUrl === 'string' && /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/.test(saved.cdpUrl) ? saved.cdpUrl : null,
+        executablePath: typeof saved.executablePath === 'string' && saved.executablePath.trim() ? saved.executablePath : null,
+        allowPrivate: saved.allowPrivate === true,
+        allowedDomains: Array.isArray(saved.allowedDomains) ? saved.allowedDomains.filter((domain) => typeof domain === 'string' && /^[a-z0-9.-]+$/i.test(domain)).map((domain) => domain.toLowerCase()) : []
+    };
+}
+export function writeBrowserConfig(stateDir, change) {
+    const next = { ...readBrowserConfig(stateDir), ...change };
+    writeJson(configPath(stateDir), next);
+    return readBrowserConfig(stateDir);
+}

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

@@ -0,0 +1,4 @@
+import type { BrowserConfig } from "./config.js";
+import type { DoctorCheck } from "../doctor/types.js";
+/** Exercises the production tool path against a synthetic page in a throwaway profile. */
+export declare function browserDiagnostic(configure: () => BrowserConfig): DoctorCheck;

package/dist/sdk/browser/diagnostics.js

@@ -0,0 +1,38 @@
+import { accessSync, constants } from 'node:fs';
+const outputText = (result) => typeof result === 'string' ? result : result.text;
+/** Exercises the production tool path against a synthetic page in a throwaway profile. */
+export function browserDiagnostic(configure) {
+    return {
+        id: 'browser', category: 'browser', title: 'Isolated browser',
+        tools: ['browser_navigate', 'browser_read', 'browser_snapshot', 'browser_click'],
+        local: async () => {
+            const config = configure();
+            if (config.executablePath)
+                accessSync(config.executablePath, constants.X_OK);
+            return { status: 'pass', evidence: `Browser tools are installed. ${config.cdpUrl ? 'A CDP endpoint is configured; diagnostics will not attach to it.' : 'A dedicated browser will be launched only after live-check confirmation.'} Browser launch is unverified.` };
+        },
+        live: {
+            notice: 'Launch a dedicated headless browser with a disposable profile, open an offline synthetic page, read its marker, and click its test button. No existing browser or profile is used.',
+            run: async (probe) => {
+                if (configure().cdpUrl)
+                    return { status: 'blocked', evidence: 'This backend is configured to attach to a browser. Isolated diagnostics will not attach to it.', remedy: 'Use a dedicated launch configuration to test browser interaction.' };
+                const needed = ['browser_navigate', 'browser_read', 'browser_snapshot', 'browser_click'];
+                if (needed.some(name => !probe.context.tools.includes(name)))
+                    return { status: 'blocked', evidence: 'The browser interaction test requires navigate, read, snapshot, and click capabilities.' };
+                const html = '<!doctype html><title>Harness Doctor</title><p>doctor-ready</p><button onclick="document.querySelector(\'p\').textContent=\'doctor-clicked\'">Diagnostic test</button>';
+                await probe.call('browser_navigate', { url: `data:text/html,${encodeURIComponent(html)}` });
+                const before = outputText(await probe.call('browser_read', {}));
+                if (!before.includes('doctor-ready'))
+                    return { status: 'fail', evidence: 'The diagnostic page marker could not be read.' };
+                const snapshot = outputText(await probe.call('browser_snapshot', {}));
+                const line = snapshot.split('\n').find(line => line.includes('button') && line.includes('Diagnostic test'));
+                const ref = line && /\b(e\d+)\b/.exec(line)?.[1];
+                if (!ref)
+                    return { status: 'fail', evidence: 'The test button was absent from the browser snapshot.' };
+                await probe.call('browser_click', { ref });
+                const after = outputText(await probe.call('browser_read', {}));
+                return after.includes('doctor-clicked') ? { status: 'pass', evidence: 'Navigation, reading, element discovery, and clicking succeeded in the disposable diagnostic browser.' } : { status: 'fail', evidence: 'Clicking did not change the expected page marker.' };
+            }
+        }
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { PluginDescriptor } from "../plugins/types.js";
+import type { WorldPart } from "../world/world.js";
+import { NetworkPolicy } from "./network.js";
+import { BrowserSession, type Launcher } from "./session.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;
+}
+export declare function browserPart(options: BrowserPartOptions): WorldPart & {
+    sessions: Map<string, BrowserSession>;
+};

package/dist/sdk/browser/index.js

@@ -0,0 +1,65 @@
+// The browser, as one part of the harness's world tools: a plugin a person can switch off, and one
+// live browser per session.
+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 { BROWSER_TOOL_NAMES, browserTools } from "./tools.js";
+export const BROWSER_PLUGIN = {
+    id: 'browser',
+    title: 'Browser',
+    description: 'A browser the agent drives: open pages that need scripts, read them, click, type and choose. Each session has its own; sign-ins are kept per agent on this device. 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 browserPart(options) {
+    const sessions = new Map();
+    const diagnosticKeys = new Set();
+    const config = () => readBrowserConfig(options.stateDir);
+    const network = options.network ?? new NetworkPolicy(config);
+    const sessionFor = (context) => {
+        let session = sessions.get(context.sessionKey);
+        if (!session) {
+            const owner = context.caller.agentId ?? context.caller.projectId ?? 'default';
+            const key = context.sessionKey;
+            const diagnostic = context.caller.surface === 'doctor';
+            if (diagnostic)
+                diagnosticKeys.add(key);
+            session = new BrowserSession({
+                key,
+                profileDir: diagnostic ? null : join(options.stateDir, 'browser', 'profiles', fileName(owner)),
+                downloadsDir: join(options.stateDir, 'browser', 'downloads', fileName(key)),
+                config: diagnostic ? () => ({ ...config(), cdpUrl: null, headed: false }) : config,
+                network,
+                launch: options.launch ?? launchBrowser,
+                idleMs: options.idleMs ?? IDLE_MS,
+                onIdle: () => void release(key)
+            });
+            sessions.set(key, session);
+        }
+        return session;
+    };
+    const release = async (key) => {
+        const session = sessions.get(key);
+        sessions.delete(key);
+        await session?.close();
+        if (diagnosticKeys.delete(key))
+            rmSync(join(options.stateDir, 'browser', 'downloads', fileName(key)), { recursive: true, force: true });
+    };
+    return {
+        plugin: BROWSER_PLUGIN,
+        diagnostics: () => [browserDiagnostic(config)],
+        sessions,
+        tools: (context) => browserTools(context, () => sessionFor(context)),
+        release,
+        close: async () => {
+            await Promise.all([...sessions.keys()].map(release));
+        }
+    };
+}

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/session.d.ts

@@ -0,0 +1,84 @@
+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;
+    /** 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>;
+}