@descryy/mcp 0.2.0 → 0.4.0

package/dist/browser/playwright-driver.js

@@ -0,0 +1,359 @@
+/**
+ * The real `BrowserDriver`, over `@descryy/runtime-browser`.
+ *
+ * ## Why the import is dynamic
+ *
+ * `@descryy/runtime-browser` is not on the npm registry yet
+ * (`mcp-browser-tools.md` §3.1 — the publish returns 429 on new-scoped-package
+ * creation). Declaring it in `package.json` today would break `npm install`
+ * for everyone, including the lanes that never touch a browser. So it is
+ * imported by specifier at call time and its absence is a **named refusal
+ * with a remedy**, exactly as a missing Chromium is.
+ *
+ * That is a temporary shape and it is written down as one: the final swap
+ * (§8's tool-count item) declares the dependency and makes this a static
+ * import. What must *not* happen in the meantime is the tools quietly
+ * appearing to work — see `provider.ts`.
+ *
+ * ## What this adds over the runtime package, and what it deliberately does not
+ *
+ * It adds exactly one thing the runtime has no API for: **element refs.** The
+ * port's contract is that an action names an element the agent has seen, and
+ * `BrowserActionCollector` acts on raw selectors. So this module enumerates
+ * the page's interactive elements, holds a Playwright `ElementHandle` per ref,
+ * and drops the whole map on navigation. Handles rather than injected `data-`
+ * attributes on purpose: stamping the DOM would make the act of observing
+ * change the page being observed, and a detached element then fails naturally
+ * instead of resolving to whatever took its place.
+ *
+ * Everything else is composition. Launch, click, type, fill, console capture,
+ * network capture, the `fetch()` initiator stack and its source-map rewrite
+ * are all the runtime package's, called rather than reimplemented.
+ *
+ * ## Rule 1
+ *
+ * No language is named here. The stack-trace parser that turns a raw browser
+ * stack into resolved frames is handed in by the caller as a module specifier
+ * — the same mechanism `runtime-registry.ts` uses for runtime adapters, for
+ * the same reason. Without one, requests are still observed and no caller
+ * edge is written; the reply says so.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { BrowserSessionCrashedError, UnknownElementRefError } from "./driver.js";
+/** The module the driver composes. Named once, imported at call time. */
+const RUNTIME_BROWSER_MODULE = "@descryy/runtime-browser";
+/**
+ * Elements an agent can act on.
+ *
+ * Deliberately narrow. A snapshot of every node on the page would be
+ * enormous, mostly unactionable, and would push the reply budget into
+ * dropping the elements that matter. `[role]` is included so an application
+ * that builds its own controls is not invisible.
+ */
+const INTERACTIVE = "a, button, input, select, textarea, [role], [onclick], summary";
+export class BrowserBackendMissingError extends Error {
+    constructor(cause) {
+        super(`Could not load ${RUNTIME_BROWSER_MODULE}: ${cause instanceof Error ? cause.message : String(cause)}. ` +
+            "This build of @descryy/mcp does not have the browser backend installed.");
+        this.name = "BrowserBackendMissingError";
+    }
+}
+export async function createPlaywrightBrowserDriver(options = {}) {
+    let runtime;
+    try {
+        runtime = (await import(__rewriteRelativeImportExtension(RUNTIME_BROWSER_MODULE)));
+    }
+    catch (error) {
+        throw new BrowserBackendMissingError(error);
+    }
+    return {
+        async launch(launchOptions) {
+            const launch = await runtime.launchBrowserSessionOrRefuse({ headless: launchOptions.headless ?? true });
+            if (!launch.launched) {
+                const { launched: _launched, ...refusal } = launch;
+                return { launched: false, ...refusal };
+            }
+            const session = await openSession(runtime, launch.session, launchOptions, options);
+            return { launched: true, session };
+        },
+    };
+}
+async function openSession(runtime, session, launchOptions, options) {
+    const emitted = [];
+    const actions = [];
+    let refs = new Map();
+    let generation = 0;
+    let closed = false;
+    let finalObservation = null;
+    const context = {
+        executionId: `mcp-browser-${session.sessionId}`,
+        configuration: { environmentTier: "tier-2-container", fidelityLevel: 2, timeoutMs: 30_000, services: {} },
+        emit: (evidence) => {
+            emitted.push(evidence);
+        },
+        ...(options.resolveSourceRoot === undefined ? {} : { resolveSourceRoot: options.resolveSourceRoot }),
+    };
+    const actionCollector = runtime.createBrowserActionCollector({
+        session,
+        ...(options.service === undefined ? {} : { service: options.service }),
+    });
+    const consoleCollector = runtime.createBrowserConsoleCollector({
+        session,
+        ...(options.service === undefined ? {} : { service: options.service }),
+        ...(options.stackParser === undefined ? {} : { stackTraceParser: options.stackParser }),
+    });
+    const networkCollector = runtime.createBrowserNetworkCollector({
+        session,
+        ...(options.service === undefined ? {} : { service: options.service }),
+        ...(options.stackParser === undefined ? {} : { stackTraceParser: options.stackParser }),
+    });
+    // Started before the first navigation, deliberately. The initiator capture
+    // wraps `fetch` via an init script, and Playwright's own contract is that
+    // an init script does not reach a document already loaded — so a collector
+    // started after navigating would observe a page it could never have
+    // instrumented, and would report an honest-looking empty stack for every
+    // request.
+    await actionCollector.start(context);
+    await consoleCollector.start(context);
+    await networkCollector.start(context);
+    await actionCollector.navigate(launchOptions.targetUrl);
+    function assertUsable() {
+        if (closed || !session.isUsable())
+            throw new BrowserSessionCrashedError(session.sessionId);
+    }
+    function resolve(ref) {
+        const found = refs.get(ref);
+        if (found === undefined)
+            throw new UnknownElementRefError(ref);
+        return found;
+    }
+    function recordAction(action, ref, mode) {
+        actions.push({ action, ref, mode, url: session.page.url(), at: new Date().toISOString() });
+    }
+    async function dropRefs() {
+        const handles = [...refs.values()].map((r) => r.handle);
+        refs = new Map();
+        await Promise.all(handles.map((h) => h.dispose().catch(() => { })));
+    }
+    return {
+        sessionId: session.sessionId,
+        startedAt: session.startedAt,
+        isUsable: () => !closed && session.isUsable(),
+        currentUrl: () => session.page.url(),
+        async navigate(url) {
+            assertUsable();
+            await dropRefs();
+            await actionCollector.navigate(url);
+            recordAction("navigate", null, null);
+        },
+        async snapshot() {
+            assertUsable();
+            await dropRefs();
+            generation += 1;
+            const handles = await session.page.$$(INTERACTIVE);
+            const elements = [];
+            for (const [index, handle] of handles.entries()) {
+                const described = await handle
+                    .evaluate((el) => {
+                    const tag = el.tagName.toLowerCase();
+                    const explicit = el.getAttribute("role");
+                    const type = el.getAttribute("type");
+                    const role = explicit ??
+                        (tag === "a"
+                            ? "link"
+                            : tag === "button" || (tag === "input" && (type === "button" || type === "submit"))
+                                ? "button"
+                                : tag === "select"
+                                    ? "combobox"
+                                    : tag === "textarea" || (tag === "input" && (type === null || type === "text" || type === "search"))
+                                        ? "textbox"
+                                        : tag === "input" && type === "checkbox"
+                                            ? "checkbox"
+                                            : tag);
+                    // A pragmatic accessible name, not a full AccName implementation:
+                    // the label a person would read, in the order a person would find
+                    // it. Named as an approximation rather than presented as the
+                    // accessibility tree's own answer.
+                    const name = el.getAttribute("aria-label") ??
+                        el.innerText?.trim() ??
+                        el.textContent?.trim() ??
+                        el.getAttribute("placeholder") ??
+                        el.getAttribute("name") ??
+                        "";
+                    return { role, name: name.slice(0, 200) };
+                })
+                    .catch(() => null);
+                if (described === null) {
+                    await handle.dispose().catch(() => { });
+                    continue;
+                }
+                const ref = `ref-${generation}-${index}`;
+                const element = {
+                    ref,
+                    role: described.role,
+                    name: described.name,
+                    // Honest: this driver acts through a held handle, not through a
+                    // selector string. Reporting a fabricated CSS path here would be a
+                    // selector nothing ever uses and that might not even match.
+                    selector: `(held handle ${ref})`,
+                };
+                refs.set(ref, { element, handle });
+                elements.push(element);
+            }
+            return { url: session.page.url(), title: await session.page.title().catch(() => ""), elements, totalElements: elements.length };
+        },
+        async click(ref) {
+            assertUsable();
+            await resolve(ref).handle.click();
+            recordAction("click", ref, null);
+            // `requestfinished` fires after the page's own handler resolves, so a
+            // drain immediately after a click would miss the request the click
+            // caused — which is the request this whole feature exists to witness.
+            await session.page.waitForTimeout(300);
+        },
+        async type(ref, text) {
+            assertUsable();
+            const { handle } = resolve(ref);
+            if (handle.pressSequentially !== undefined)
+                await handle.pressSequentially(text);
+            else if (handle.type !== undefined)
+                await handle.type(text);
+            else
+                throw new Error("this Playwright build exposes no keystroke-level typing method");
+            recordAction("type", ref, "append");
+            await session.page.waitForTimeout(300);
+        },
+        async fill(ref, text) {
+            assertUsable();
+            await resolve(ref).handle.fill(text);
+            recordAction("fill", ref, "replace");
+            await session.page.waitForTimeout(300);
+        },
+        async drainEvidence() {
+            const observation = collect(emitted, actions);
+            emitted.length = 0;
+            actions.length = 0;
+            return observation;
+        },
+        async close() {
+            if (finalObservation !== null)
+                return finalObservation;
+            closed = true;
+            // Collectors are stopped before the observation is taken: a stop
+            // flushes whatever the collector was still holding, and taking the
+            // observation first would drop exactly that.
+            await actionCollector.stop().catch(() => { });
+            await consoleCollector.stop().catch(() => { });
+            await networkCollector.stop().catch(() => { });
+            const observation = collect(emitted, actions);
+            emitted.length = 0;
+            actions.length = 0;
+            await dropRefs();
+            await session.close().catch(() => { });
+            finalObservation = observation;
+            return observation;
+        },
+    };
+}
+/**
+ * Turn what the collectors emitted into the port's vocabulary.
+ *
+ * The request/response join is on `requestId`, because a `NETWORK_REQUEST`
+ * carries the method, the URL and the call-site stack while only the matching
+ * `NETWORK_RESPONSE` knows the status. A request with no response is kept with
+ * `status: null` — "never answered" is a different fact from a 500, and the
+ * port says so.
+ */
+function collect(emitted, actions) {
+    // Two joins, in priority order, because `requestId` is a *correlation
+    // header* and not a transport id: it exists only when the application
+    // itself propagates one. The fixture's own delete sets `x-request-id`, so
+    // an id-only join looked correct while silently reporting `status: null`
+    // for every request the page issued without one — which is most of them.
+    const statusByRequestId = new Map();
+    const statusByUrl = new Map();
+    for (const evidence of emitted) {
+        if (evidence.eventType !== "NETWORK_RESPONSE")
+            continue;
+        const status = evidence.payload["status"];
+        if (typeof status !== "number")
+            continue;
+        if (evidence.requestId !== null)
+            statusByRequestId.set(evidence.requestId, status);
+        const url = evidence.payload["url"];
+        // Last response wins: a page that requests the same URL twice reports the
+        // most recent outcome, which is the one a caller reading this reply is
+        // asking about.
+        if (typeof url === "string")
+            statusByUrl.set(url, status);
+    }
+    const requests = [];
+    const consoleErrors = [];
+    for (const evidence of emitted) {
+        if (evidence.eventType === "NETWORK_REQUEST") {
+            const method = evidence.payload["method"];
+            const url = evidence.payload["url"];
+            if (typeof method !== "string" || typeof url !== "string")
+                continue;
+            requests.push({
+                method,
+                url,
+                status: (evidence.requestId === null ? undefined : statusByRequestId.get(evidence.requestId)) ??
+                    statusByUrl.get(url) ??
+                    null,
+                stackText: renderStack(evidence.stackTrace),
+                stackTrace: evidence.stackTrace,
+                at: evidence.timestamp,
+            });
+            continue;
+        }
+        // An uncaught page error and a console error are both "the page reported
+        // something went wrong"; a caller triaging them does not need to know
+        // which listener fired.
+        if (evidence.eventType === "EXCEPTION" || evidence.eventType === "CONSOLE_MESSAGE") {
+            const level = evidence.payload["level"] ?? evidence.payload["type"];
+            if (evidence.eventType === "CONSOLE_MESSAGE" && level !== "error")
+                continue;
+            const text = evidence.payload["text"] ?? evidence.payload["message"];
+            consoleErrors.push({
+                text: typeof text === "string" ? text : JSON.stringify(evidence.payload),
+                stackText: renderStack(evidence.stackTrace),
+                at: evidence.timestamp,
+            });
+        }
+    }
+    return { actions: [...actions], consoleErrors, requests };
+}
+/**
+ * A short, readable rendering of a parsed stack.
+ *
+ * `StackTrace` carries frames, not the original text — the raw string is
+ * consumed by the parser and deliberately not kept, since a parsed frame with
+ * a resolved on-disk path is strictly more useful than the `http://` line it
+ * came from. So the port's `stackText` is rendered from the frames rather
+ * than passed through, and it is for a human reading the reply: the R4 write
+ * uses `stackTrace`, never this.
+ *
+ * The primary frame is marked, because it is the one a developer should be
+ * sent to and it is not always the innermost.
+ */
+function renderStack(stack) {
+    if (stack === null || stack.frames.length === 0)
+        return null;
+    return stack.frames
+        .slice(0, 5)
+        .map((frame, index) => {
+        const where = `${frame.location.file}:${frame.location.line}`;
+        const name = frame.location.functionName ?? "(anonymous)";
+        return `${index === stack.primaryFrameIndex ? "> " : "  "}at ${name} (${where})`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=playwright-driver.js.map

package/dist/browser/playwright-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-driver.js","sourceRoot":"","sources":["../../src/browser/playwright-driver.ts"],"names":[],"mappings":"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"}

package/dist/browser/provider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Where a tool gets a browser.
+ *
+ * `@descryy/runtime-browser` is not on the registry yet (§3.1), so this build
+ * has no real driver in it. That absence is handled the way this codebase
+ * handles every expected inability: as a **named refusal with a remedy**,
+ * returned rather than thrown, and never as a tool that quietly does nothing.
+ *
+ * Rule 7 is the whole point of this file. A browser tool in a build with no
+ * browser backend must say *"this build cannot do that, and here is why"* —
+ * not fail obscurely inside a missing import, and certainly not return an
+ * empty snapshot that reads like a page with no elements on it.
+ */
+import type { StackTraceParser } from "@descryy/runtime-backend-observation";
+import type { ServiceRootLookup } from "@descryy/runtime-contracts";
+import type { BrowserDriver } from "./driver.ts";
+/**
+ * Builds the driver one session will use.
+ *
+ * Takes the per-session facts a driver cannot know for itself: which parser
+ * can read this application's stack traces, and which on-disk root serves the
+ * origin being driven. Both are the caller's to state — see
+ * `stack-parser.ts` for why the parser cannot be chosen here, and
+ * `browser_start_session`'s `documentRoot` for why the root cannot be
+ * guessed.
+ */
+export type BrowserDriverFactory = (options: {
+    readonly stackParser?: StackTraceParser;
+    readonly resolveSourceRoot?: (origin: string) => ServiceRootLookup;
+    readonly service?: string;
+}) => Promise<BrowserDriver>;
+export interface BrowserBackendUnavailable {
+    readonly available: false;
+    readonly reason: string;
+    readonly remedy: string;
+}
+export type BrowserBackend = {
+    readonly available: true;
+    readonly createDriver: BrowserDriverFactory;
+} | BrowserBackendUnavailable;
+/**
+ * The stand-in used until the real driver is wired at the final swap.
+ *
+ * Deliberately not a driver that launches nothing successfully — that would
+ * make every browser tool return a plausible, empty, wrong answer. It is an
+ * explicit unavailability instead.
+ */
+export declare const BROWSER_BACKEND_NOT_INSTALLED: BrowserBackendUnavailable;
+//# sourceMappingURL=provider.d.ts.map

package/dist/browser/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/browser/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;AAE7B,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAA;CAAE,GAAG,yBAAyB,CAAC;AAEnI;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,yBAO3C,CAAC"}

package/dist/browser/provider.js

@@ -0,0 +1,28 @@
+/**
+ * Where a tool gets a browser.
+ *
+ * `@descryy/runtime-browser` is not on the registry yet (§3.1), so this build
+ * has no real driver in it. That absence is handled the way this codebase
+ * handles every expected inability: as a **named refusal with a remedy**,
+ * returned rather than thrown, and never as a tool that quietly does nothing.
+ *
+ * Rule 7 is the whole point of this file. A browser tool in a build with no
+ * browser backend must say *"this build cannot do that, and here is why"* —
+ * not fail obscurely inside a missing import, and certainly not return an
+ * empty snapshot that reads like a page with no elements on it.
+ */
+/**
+ * The stand-in used until the real driver is wired at the final swap.
+ *
+ * Deliberately not a driver that launches nothing successfully — that would
+ * make every browser tool return a plausible, empty, wrong answer. It is an
+ * explicit unavailability instead.
+ */
+export const BROWSER_BACKEND_NOT_INSTALLED = {
+    available: false,
+    reason: "This build of @descryy/mcp has no browser backend. The browser tools are declared so a caller can see " +
+        "they exist and what they would need, but nothing in this build can drive a page — @descryy/runtime-browser " +
+        "is not yet part of the installed closure.",
+    remedy: "Install a build of @descryy/mcp that depends on @descryy/runtime-browser.",
+};
+//# sourceMappingURL=provider.js.map

package/dist/browser/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/browser/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+BH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA8B;IACtE,SAAS,EAAE,KAAK;IAChB,MAAM,EACJ,wGAAwG;QACxG,6GAA6G;QAC7G,2CAA2C;IAC7C,MAAM,EAAE,2EAA2E;CACpF,CAAC"}

package/dist/browser/registry.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Live browser sessions belonging to one connection — `mcp-browser-tools.md`
+ * §4.
+ *
+ * ## Why this is the hard part
+ *
+ * Every other tool on this surface is one-shot. It opens what it needs,
+ * answers, and holds nothing; a crash in the middle costs the caller one
+ * reply. A browser process that outlives a call is a different shape
+ * entirely, and the failure it introduces is not "a call fails" but "a
+ * process is still running on the developer's machine an hour after the
+ * agent stopped caring about it".
+ *
+ * So the design rule here is that **there is no path on which a session stops
+ * being tracked without its browser being closed and its evidence being
+ * handed back**. Four paths reach that state — idle timeout, client
+ * disconnect, crash, explicit close — and they converge on one private
+ * function, `reap`, rather than each doing their own teardown. They were four
+ * separate implementations in the first draft and the evidence flush was
+ * correct on three of them.
+ *
+ * ## Evidence is held, not dropped, and not silently discarded either
+ *
+ * A timeout or a disconnect has no reply to attach evidence to. Discarding it
+ * would be the failure rule 7 names — silently doing less — so a reaped
+ * session leaves a `ReapedSession` record behind carrying the reason and the
+ * final flush, and the next caller who names that id receives it instead of a
+ * bare "unknown session". That record is what turns "your session vanished"
+ * into "your session was idle for five minutes; here is what it saw before it
+ * went".
+ *
+ * ## Per connection, never global
+ *
+ * A registry is created per `Session`, which is created per connection. A
+ * global one would let a second client `use` a first client's browser by
+ * guessing a uuid, and would make the disconnect reap ambiguous about whose
+ * sessions it was reaping.
+ */
+import type { BrowserDriver, BrowserLaunchOptions, BrowserObservation, BrowserPageSession, ChromiumRefusal } from "./driver.ts";
+/**
+ * How long a session may go untouched before it is torn down.
+ *
+ * A starting value, not a measurement, in this repo's usual sense: no agent
+ * has yet been observed pausing mid-exploration, so there is nothing to fit
+ * it to. Five minutes is long enough to survive a model thinking, short
+ * enough that a forgotten browser is a five-minute leak rather than an
+ * overnight one. It is deliberately the same figure as the action handshake's
+ * token TTL — an agent that cannot decide within one is unlikely to be coming
+ * back for the other.
+ */
+export declare const BROWSER_IDLE_TIMEOUT_MS: number;
+/**
+ * How many sessions one connection may hold open at once.
+ *
+ * Small on purpose. A calling agent driving more than a couple of browsers
+ * simultaneously is not doing something this surface was built for, and each
+ * one is a real Chromium. Three leaves room for the honest case — a
+ * comparison between two states, plus one being opened — without letting a
+ * loop with a missing `browser_close_session` fill the machine.
+ */
+export declare const MAX_BROWSER_SESSIONS = 3;
+export type ReapReason = "idleTimeout" | "clientDisconnect" | "crashed" | "closed";
+/**
+ * DEC-270's vocabulary, read here and defined nowhere near here.
+ *
+ * A browser session's safety level is the environment profile's — the same
+ * field `observe_runtime` already reads. Declaring a second, browser-only
+ * notion of "safe" is how a runtime run and a browser run end up disagreeing
+ * about the same environment, which is the failure item 27 exists to prevent.
+ * Null means no profile was supplied, in which case the session's consent is
+ * the only authorization and it governs alone.
+ */
+export type BrowserSafetyLevel = "readOnly" | "write" | "destructiveWithApproval";
+export interface BrowserSessionEntry {
+    readonly sessionId: string;
+    /**
+     * The run id every R4 edge this session witnesses is stamped with.
+     *
+     * One per session, not one per call: an edge's `observedByRun` answers
+     * "which run saw this", and a run that changed identity between a click and
+     * the request it caused would make that answer meaningless.
+     */
+    readonly runId: string;
+    readonly page: BrowserPageSession;
+    /** The profile this session was opened under, or null when none was declared. */
+    readonly profile: {
+        readonly name: string;
+        readonly safetyLevel: BrowserSafetyLevel;
+    } | null;
+    /**
+     * The origin `browser_start_session` was consented for.
+     *
+     * Recorded at open time rather than read from the page later: the consent
+     * ruling binds the grant to the origin the developer approved, and a page
+     * that has since navigated is exactly the case where re-deriving it would
+     * launder a cross-origin move into an approved one.
+     */
+    readonly consentedOrigin: string;
+    readonly openedAt: number;
+    readonly lastUsedAt: number;
+}
+export interface ReapedSession {
+    readonly sessionId: string;
+    readonly reason: ReapReason;
+    readonly observation: BrowserObservation;
+    readonly at: number;
+}
+export type OpenResult = {
+    readonly opened: true;
+    readonly entry: BrowserSessionEntry;
+} | {
+    readonly opened: false;
+    readonly kind: "atCapacity";
+    readonly reason: string;
+} | ({
+    readonly opened: false;
+    readonly kind: "chromiumNotInstalled";
+} & ChromiumRefusal);
+export type UseResult = {
+    readonly ok: true;
+    readonly entry: BrowserSessionEntry;
+} | {
+    readonly ok: false;
+    readonly kind: "unknown";
+    readonly reason: string;
+} | {
+    readonly ok: false;
+    readonly kind: "crashed" | "reaped";
+    readonly reason: string;
+    readonly reaped: ReapedSession;
+};
+export interface BrowserOpenOptions extends BrowserLaunchOptions {
+    /** The environment profile this session runs under. Read, never invented — see `BrowserSafetyLevel`. */
+    readonly profile?: {
+        readonly name: string;
+        readonly safetyLevel: BrowserSafetyLevel;
+    } | null;
+}
+export interface BrowserSessionRegistryOptions {
+    readonly now?: () => number;
+    readonly maxSessions?: number;
+    readonly idleTimeoutMs?: number;
+    /**
+     * Whether to run the background idle sweep.
+     *
+     * True in production: a session that goes idle because the agent wandered
+     * off is precisely the session that will never trigger a lazy sweep, so the
+     * timeout cannot be enforced only on the next call. The timer is `unref`'d,
+     * so it never holds the process open by itself.
+     *
+     * False in tests, which drive `sweepIdle()` against an injected clock —
+     * a real timer would make the idle assertions take real minutes.
+     */
+    readonly startSweeper?: boolean;
+}
+export interface BrowserSessionRegistry {
+    readonly idleTimeoutMs: number;
+    readonly maxSessions: number;
+    open(driver: BrowserDriver, options: BrowserOpenOptions): Promise<OpenResult>;
+    /**
+     * Look a session up for use, touching its idle clock. Detects a crash
+     * before handing anything back.
+     *
+     * Asynchronous because the crash path is not a lookup — it is a teardown.
+     * A synchronous `use` would have to either drop the dead page's final
+     * evidence or pretend to have collected it, and the first draft of this
+     * file did the second: it returned a record it then filled in from a
+     * floating promise, so the flush landed after the caller had already read
+     * the record. Awaiting the reap here is what makes "a crash flushes what
+     * preceded it" true rather than nearly true.
+     */
+    use(sessionId: string): Promise<UseResult>;
+    close(sessionId: string): Promise<BrowserObservation>;
+    sweepIdle(): Promise<readonly ReapedSession[]>;
+    reapAll(reason: ReapReason): Promise<readonly ReapedSession[]>;
+    reaped(sessionId: string): ReapedSession | undefined;
+    openCount(): number;
+    /** Stop the background sweeper. Called when the connection's `Session` is disposed. */
+    stop(): void;
+}
+export declare function createBrowserSessionRegistry(options?: BrowserSessionRegistryOptions): BrowserSessionRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/browser/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/browser/registry.ts"],"names":[],"mappings":"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"}