@oscharko-dev/keiko 0.1.5 → 0.1.7

package/dist/tools/browser/session.js

@@ -1,748 +1,4 @@
-// ADR-0017 D3/D6/D9 — browser session manager. In-memory Map of sessionId→record, 4-session cap,
-// 30-min idle TTL, fresh Target.createTarget only (never attaches to user tabs), post-navigate
-// frameNavigated origin re-check, dry-run-by-default screenshots, redactor over captured HTML.
-//
-// Security invariants:
-//   • webSocketDebuggerUrl from /json/version is validated for loopback host + matching port (H1).
-//   • pendingScreenshots per session is capped at MAX_PENDING_SCREENSHOTS (1) with insertion-order
-//     eviction to bound memory use (M1).
-//   • Session slot is reserved synchronously before any await to prevent TOCTOU on the limit (M2).
-//
-// Composition: validators (M1) + CDP client (M2) + side-file writer (M3) + the existing audit
-// redactor. No new safety primitives — every guard is reused.
-import { randomUUID } from "node:crypto";
-import { CdpClient } from "./cdp-client.js";
-import { BrowserToolError } from "./errors.js";
-import { isLoopbackHost, isLoopbackUrl, normalizeCdpPort, normalizeNavigateUrl, } from "./validators.js";
-import { resolveCostClass } from "../../audit/aggregate.js";
-import { writeSideFile } from "../../audit/side-file.js";
-import { EVIDENCE_SCHEMA_VERSION, } from "../../audit/types.js";
-import { HARNESS_VERSION } from "../../harness/session.js";
-const MAX_SESSIONS = 4;
-const SESSION_IDLE_TTL_MS = 30 * 60 * 1000;
-const MAX_SCREENSHOT_BYTES = 10 * 1024 * 1024;
-const MAX_CONTENT_BYTES = 2 * 1024 * 1024;
-const MAX_VERSION_BODY_BYTES = 64_000;
-const VERSION_FETCH_TIMEOUT_MS = 5000;
-// M1: cap per-session pending screenshots; oldest (insertion-order) is evicted on overflow.
-const MAX_PENDING_SCREENSHOTS = 1;
-const DEFAULT_VIEWPORT = { width: 1280, height: 800 };
-const FRAGMENT_RECHECK_TIMEOUT_MS = 5000;
-const VERSION_PATH = "/json/version";
-function defaultRedactor(value) {
-    return value;
-}
-// H1: validate webSocketDebuggerUrl host+port so a malicious /json/version responder
-// cannot redirect the WebSocket to a non-loopback host (ADR-0017 D2 layer-1).
-function assertWsUrlTrusted(ws, expectedPort) {
-    let parsed;
-    try {
-        parsed = new URL(ws);
-    }
-    catch {
-        throw new BrowserToolError("CDP_TRANSPORT_REFUSED", "CDP endpoint returned an invalid WebSocket URL.");
-    }
-    const host = parsed.hostname.startsWith("[") && parsed.hostname.endsWith("]")
-        ? parsed.hostname.slice(1, -1)
-        : parsed.hostname;
-    const port = parsed.port === "" ? (parsed.protocol === "wss:" ? 443 : 80) : Number.parseInt(parsed.port, 10);
-    if (!isLoopbackHost(host) || port !== expectedPort) {
-        throw new BrowserToolError("CDP_TRANSPORT_REFUSED", "CDP endpoint returned a WebSocket URL that is not on the expected loopback address.");
-    }
-}
-function browserWsUrlFromVersion(version, fallbackPort) {
-    if (typeof version !== "object" || version === null) {
-        return defaultVersionInfo(fallbackPort);
-    }
-    const rec = version;
-    const ws = rec.webSocketDebuggerUrl;
-    if (typeof ws !== "string" || !ws.startsWith("ws://")) {
-        return defaultVersionInfo(fallbackPort);
-    }
-    assertWsUrlTrusted(ws, fallbackPort);
-    const ua = rec["User-Agent"] ?? rec.userAgent;
-    const product = rec.Browser ?? rec.product;
-    return {
-        url: ws,
-        userAgent: typeof ua === "string" ? ua : null,
-        browserVersion: typeof product === "string" ? product : null,
-    };
-}
-function defaultVersionInfo(port) {
-    return {
-        url: `ws://127.0.0.1:${String(port)}/devtools/browser`,
-        userAgent: null,
-        browserVersion: null,
-    };
-}
-async function fetchVersionJson(url) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => {
-        controller.abort();
-    }, VERSION_FETCH_TIMEOUT_MS);
-    try {
-        const res = await fetch(url, { redirect: "manual", signal: controller.signal });
-        if (res.url !== url || (res.status >= 300 && res.status < 400)) {
-            throw new BrowserToolError("CDP_TRANSPORT_REFUSED", "CDP version endpoint redirected.");
-        }
-        if (!res.ok) {
-            throw new BrowserToolError("CHROME_UNREACHABLE", "CDP version endpoint returned a non-200.");
-        }
-        const text = await readCappedText(res);
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            throw new BrowserToolError("CHROME_UNREACHABLE", "CDP version endpoint returned invalid JSON.");
-        }
-    }
-    catch (error) {
-        if (error instanceof BrowserToolError)
-            throw error;
-        throw new BrowserToolError("CHROME_UNREACHABLE", "CDP version endpoint is unreachable.");
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-function isChromiumUserAgent(userAgent) {
-    if (userAgent === null)
-        return true;
-    // Single-pass linear scan — substring matches only, no regex (ADR-0002 ReDoS gate).
-    return (userAgent.includes("Chrome") ||
-        userAgent.includes("Chromium") ||
-        userAgent.includes("HeadlessChrome"));
-}
-function safeOrigin(url) {
-    try {
-        return new URL(url).origin;
-    }
-    catch {
-        return null;
-    }
-}
-function evidenceStringField(key, value) {
-    return typeof value === "string" ? { [key]: value } : {};
-}
-function evidenceNumberField(key, value) {
-    return typeof value === "number" ? { [key]: value } : {};
-}
-function evidenceBooleanField(key, value) {
-    return typeof value === "boolean" ? { [key]: value } : {};
-}
-function evidenceNullableNumberField(key, value) {
-    return typeof value === "number" || value === null ? { [key]: value } : {};
-}
-function browserViewportPayload(value) {
-    if (typeof value !== "object" || value === null)
-        return undefined;
-    const rec = value;
-    return typeof rec.width === "number" && typeof rec.height === "number"
-        ? { width: rec.width, height: rec.height }
-        : undefined;
-}
-function evidenceViewportField(value) {
-    const viewportPx = browserViewportPayload(value);
-    return viewportPx === undefined ? {} : { viewportPx };
-}
-function isSubframeNavigation(params) {
-    return typeof params.frame?.parentId === "string" && params.frame.parentId.length > 0;
-}
-function mainFrameUrl(params) {
-    const url = params.frame?.url;
-    if (typeof url !== "string" || url.length === 0 || url === "about:blank")
-        return null;
-    return url;
-}
-async function readCappedText(res) {
-    if (res.body === null)
-        return "";
-    const reader = res.body.getReader();
-    const chunks = [];
-    let total = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        total += value.byteLength;
-        if (total > MAX_VERSION_BODY_BYTES) {
-            await reader.cancel().catch(() => undefined);
-            throw new BrowserToolError("PAYLOAD_TOO_LARGE", "CDP version response exceeds the size limit.");
-        }
-        chunks.push(value);
-    }
-    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8");
-}
-// The class form keeps each method small (max-lines-per-function gate) while sharing one private
-// state region. Method names match the BrowserSessionManager port shape.
-class BrowserSessionManagerImpl {
-    opts;
-    redactor;
-    clientFactory;
-    fetchVersion;
-    idleTtlMs;
-    nowMs;
-    sessions = new Map();
-    subscribers = new Map();
-    counters = { navigations: 0 };
-    constructor(opts) {
-        this.opts = opts;
-        this.redactor = opts.redactor ?? defaultRedactor;
-        this.clientFactory =
-            opts.cdpClientFactory ?? ((url, options) => new CdpClient(url, options));
-        this.fetchVersion = opts.fetchVersion ?? fetchVersionJson;
-        this.idleTtlMs = opts.idleTtlMs ?? SESSION_IDLE_TTL_MS;
-        this.nowMs = opts.nowMs ?? (() => Date.now());
-    }
-    toEvidenceEvent(event) {
-        const p = event.payload;
-        return {
-            schemaVersion: "1",
-            type: event.type,
-            sessionId: event.sessionId,
-            seq: event.seq,
-            ts: event.ts,
-            ...evidenceStringField("originOnly", p.originOnly),
-            ...evidenceNullableNumberField("httpStatus", p.httpStatus),
-            ...evidenceNumberField("captureSeq", p.captureSeq),
-            ...evidenceBooleanField("persisted", p.persisted),
-            ...evidenceViewportField(p.viewportPx),
-            ...evidenceStringField("path", p.path),
-            ...evidenceStringField("sha256", p.sha256),
-            ...evidenceNumberField("bytes", p.bytes),
-            ...evidenceNumberField("byteLength", p.byteLength),
-            ...evidenceStringField("reason", p.reason),
-            ...evidenceStringField("warning", p.warning),
-            ...evidenceStringField("code", p.code),
-            ...evidenceStringField("message", p.message),
-        };
-    }
-    buildManifest(record) {
-        const finishedAt = record.closedAt ?? this.nowMs();
-        const manifest = {
-            evidenceSchemaVersion: EVIDENCE_SCHEMA_VERSION,
-            run: {
-                runId: record.runId,
-                fingerprint: record.fingerprint,
-                harnessVersion: HARNESS_VERSION,
-                taskType: "browser-capture",
-                outcome: "completed",
-                startedAt: record.startedAt,
-                finishedAt,
-                durationMs: Math.max(0, finishedAt - record.startedAt),
-            },
-            model: { modelId: "browser-tool", costClass: resolveCostClass("browser-tool") },
-            usageTotals: { promptTokens: 0, completionTokens: 0, requestCount: 0, totalLatencyMs: 0 },
-            stateTransitions: [],
-            toolCalls: [],
-            commandExecutions: [],
-            browser: {
-                sessionId: record.id,
-                cdpPort: record.cdpPort,
-                targetId: record.targetId,
-                status: record.closed ? "closed" : "open",
-                startedAt: record.startedAt,
-                ...(record.closedAt === undefined ? {} : { closedAt: record.closedAt }),
-                ...(record.closeReason === undefined ? {} : { closeReason: record.closeReason }),
-                ...(record.lastOriginOnly === null ? {} : { lastOriginOnly: record.lastOriginOnly }),
-                events: record.auditEvents,
-                ...(record.screenshots.length === 0 ? {} : { screenshots: record.screenshots }),
-                ...(record.contentCaptures.length === 0 ? {} : { contentCaptures: record.contentCaptures }),
-            },
-        };
-        const redacted = this.redactor(manifest);
-        return typeof redacted === "object" && redacted !== null
-            ? redacted
-            : manifest;
-    }
-    persistRecord(record) {
-        const store = this.opts.evidenceStore;
-        if (store === undefined)
-            return;
-        const manifest = this.buildManifest(record);
-        store.put(record.runId, JSON.stringify(manifest, null, 2));
-    }
-    emitRecord(record, kind, payload, ts = this.nowMs()) {
-        record.auditSeq += 1;
-        const event = {
-            schemaVersion: "1",
-            type: `browser:${kind}`,
-            runId: record.runId,
-            fingerprint: record.fingerprint,
-            seq: record.auditSeq,
-            ts,
-            kind,
-            sessionId: record.id,
-            payload,
-        };
-        record.auditEvents.push(this.toEvidenceEvent(event));
-        this.persistRecord(record);
-        this.fanout(event);
-        return event;
-    }
-    emitErrorRecord(record, code, message) {
-        this.emitRecord(record, "error", { code, message });
-    }
-    async runSessionAction(sessionId, action) {
-        const record = this.requireRecord(sessionId);
-        try {
-            return await action(record);
-        }
-        catch (error) {
-            if (error instanceof BrowserToolError) {
-                this.emitErrorRecord(record, error.code, error.message);
-            }
-            throw error;
-        }
-    }
-    checkStatus = async (cdpPort) => {
-        normalizeCdpPort(cdpPort);
-        try {
-            const url = `http://127.0.0.1:${String(cdpPort)}${VERSION_PATH}`;
-            const version = await this.fetchVersion(url);
-            const meta = browserWsUrlFromVersion(version, cdpPort);
-            if (!isChromiumUserAgent(meta.userAgent)) {
-                throw new BrowserToolError("CHROME_VERSION_MISMATCH", "CDP endpoint is not a Chromium-based browser.");
-            }
-            return {
-                reachable: true,
-                userAgent: meta.userAgent,
-                browserVersion: meta.browserVersion,
-                webSocketDebuggerUrl: meta.url,
-            };
-        }
-        catch (error) {
-            if (error instanceof BrowserToolError)
-                throw error;
-            return {
-                reachable: false,
-                userAgent: null,
-                browserVersion: null,
-                webSocketDebuggerUrl: null,
-            };
-        }
-    };
-    buildPlaceholder(id, cdpPort) {
-        // A closed sentinel record that reserves the sessions slot without an active CdpClient.
-        // It is replaced by the live record inside attachAndRegister once the CDP handshake
-        // completes. Because closed=true, requireRecord and closeSession treat it as unavailable.
-        const noop = () => undefined;
-        const fakeClient = {
-            connect: () => Promise.resolve(),
-            send: () => Promise.resolve({}),
-            onEvent: () => noop,
-            onClose: () => noop,
-            close: noop,
-            isClosed: () => true,
-            closeCause: () => undefined,
-        };
-        const now = this.nowMs();
-        return {
-            id,
-            cdpPort,
-            targetId: "",
-            client: fakeClient,
-            cdpSessionId: "",
-            runId: id.replace(/-/g, ""),
-            fingerprint: `browser-${id.replace(/-/g, "")}`,
-            startedAt: now,
-            closedAt: undefined,
-            closeReason: undefined,
-            lastUrl: null,
-            lastOriginOnly: null,
-            expectedOriginOnly: null,
-            originAllowed: false,
-            captureSeq: 0,
-            auditSeq: 0,
-            auditEvents: [],
-            screenshots: [],
-            contentCaptures: [],
-            pendingScreenshots: new Map(),
-            idleTimer: undefined,
-            lastTouchedMs: now,
-            closed: true,
-            removeCdpListener: noop,
-            removeCdpCloseListener: noop,
-        };
-    }
-    openSession = async (cdpPort) => {
-        normalizeCdpPort(cdpPort);
-        // M2: reserve the slot synchronously before any await, closing the TOCTOU window where
-        // concurrent calls could each pass the size check and then all succeed.
-        if (this.sessions.size >= MAX_SESSIONS) {
-            throw new BrowserToolError("SESSION_LIMIT_EXCEEDED", "Too many active browser sessions.");
-        }
-        const reservedId = randomUUID();
-        const placeholder = this.buildPlaceholder(reservedId, cdpPort);
-        this.sessions.set(reservedId, placeholder);
-        try {
-            const versionInfo = await this.checkStatus(cdpPort);
-            if (!versionInfo.reachable || versionInfo.webSocketDebuggerUrl === null) {
-                throw new BrowserToolError("CHROME_UNREACHABLE", "CDP endpoint is not reachable.");
-            }
-            const client = this.clientFactory(versionInfo.webSocketDebuggerUrl, {});
-            try {
-                return await this.attachAndRegister(client, cdpPort, reservedId);
-            }
-            catch (error) {
-                client.close();
-                if (error instanceof BrowserToolError)
-                    throw error;
-                throw new BrowserToolError("CHROME_UNREACHABLE", "Failed to open browser session.");
-            }
-        }
-        catch (error) {
-            this.sessions.delete(reservedId);
-            throw error;
-        }
-    };
-    async attachAndRegister(client, cdpPort, reservedId) {
-        await client.connect();
-        const target = await client.send("Target.createTarget", {
-            url: "about:blank",
-        });
-        const attach = await client.send("Target.attachToTarget", {
-            targetId: target.targetId,
-            flatten: true,
-        });
-        const record = this.buildRecord(client, cdpPort, target.targetId, attach.sessionId, reservedId);
-        record.removeCdpListener = client.onEvent(this.frameNavigatedListener(record));
-        record.removeCdpCloseListener = client.onClose((reason) => {
-            if (reason === "explicit")
-                return;
-            void this.closeRecord(record, "chrome-disconnected", false).catch(() => undefined);
-        });
-        await client.send("Page.enable", {}, attach.sessionId);
-        this.sessions.set(record.id, record);
-        this.touch(record);
-        await this.emitTrustWarningForProfileMetadata(client, record);
-        this.emitRecord(record, "session-opened", { cdpPort, targetId: target.targetId });
-        return {
-            sessionId: record.id,
-            cdpPort,
-            targetId: target.targetId,
-            status: "open",
-            createdAt: this.nowMs(),
-        };
-    }
-    buildRecord(client, cdpPort, targetId, cdpSessionId, id = randomUUID()) {
-        const runId = id.replace(/-/g, "");
-        const now = this.nowMs();
-        return {
-            id,
-            cdpPort,
-            targetId,
-            client,
-            cdpSessionId,
-            runId,
-            fingerprint: `browser-${runId}`,
-            startedAt: now,
-            closedAt: undefined,
-            closeReason: undefined,
-            lastUrl: null,
-            lastOriginOnly: null,
-            expectedOriginOnly: null,
-            originAllowed: false,
-            captureSeq: 0,
-            auditSeq: 0,
-            auditEvents: [],
-            screenshots: [],
-            contentCaptures: [],
-            pendingScreenshots: new Map(),
-            idleTimer: undefined,
-            lastTouchedMs: now,
-            closed: false,
-            removeCdpListener: () => undefined,
-            removeCdpCloseListener: () => undefined,
-        };
-    }
-    async emitTrustWarningForProfileMetadata(client, record) {
-        const browser = await client
-            .send("Browser.getVersion")
-            .catch(() => null);
-        const commandLine = browser?.commandLine;
-        if (typeof commandLine === "string" && commandLine.includes("--user-data-dir=")) {
-            return;
-        }
-        const warning = browser !== null &&
-            typeof browser.userAgent === "string" &&
-            browser.userAgent.includes("Headless")
-            ? "Headless Chromium detected; verify ephemeral --user-data-dir."
-            : "Chrome command-line metadata unavailable; verify ephemeral --user-data-dir.";
-        if (warning.length > 0) {
-            this.emitRecord(record, "trust-warning", {
-                warning,
-            });
-        }
-    }
-    closeSession = async (sessionId) => {
-        const record = this.sessions.get(sessionId);
-        if (record === undefined || record.closed)
-            return;
-        await this.closeRecord(record, "explicit", true);
-    };
-    async closeRecord(record, reason, closeTarget) {
-        if (record.closed)
-            return;
-        record.closed = true;
-        record.closedAt = this.nowMs();
-        record.closeReason = reason;
-        if (record.idleTimer !== undefined)
-            clearTimeout(record.idleTimer);
-        record.removeCdpListener();
-        record.removeCdpCloseListener();
-        if (closeTarget) {
-            try {
-                await record.client.send("Target.closeTarget", { targetId: record.targetId });
-            }
-            catch {
-                // Best-effort cleanup; the BFF is shutting the session down regardless.
-            }
-            record.client.close();
-        }
-        this.sessions.delete(record.id);
-        try {
-            this.emitRecord(record, "session-closed", { reason });
-        }
-        finally {
-            this.subscribers.delete(record.id);
-        }
-    }
-    navigate = async (sessionId, url) => {
-        return this.runSessionAction(sessionId, async (record) => {
-            const normalized = normalizeNavigateUrl(url);
-            this.touch(record);
-            record.originAllowed = false;
-            record.lastUrl = null;
-            record.lastOriginOnly = null;
-            record.expectedOriginOnly = normalized.originOnly;
-            const cdpStatus = await this.invokeNavigate(record, normalized.url);
-            await this.waitForOriginRecheck(record, normalized.originOnly);
-            // record.originAllowed is mutated by the async frameNavigated listener; the TS narrower can't
-            // see across the awaited recheck so a runtime guard remains required here.
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            if (!record.originAllowed) {
-                throw new BrowserToolError("ORIGIN_NOT_ALLOWED", "Post-navigate origin is not on the requested loopback origin.");
-            }
-            this.counters.navigations += 1;
-            this.emitRecord(record, "navigated", {
-                originOnly: record.lastOriginOnly,
-                httpStatus: cdpStatus,
-            });
-            return { originOnly: normalized.originOnly, httpStatus: cdpStatus };
-        });
-    };
-    async invokeNavigate(record, url) {
-        const result = await record.client.send("Page.navigate", { url }, record.cdpSessionId);
-        return typeof result.httpStatus === "number" ? result.httpStatus : null;
-    }
-    async waitForOriginRecheck(record, expectedOrigin) {
-        const deadline = this.nowMs() + FRAGMENT_RECHECK_TIMEOUT_MS;
-        while (record.lastUrl === null && this.nowMs() < deadline) {
-            await new Promise((resolve) => {
-                setTimeout(resolve, 20);
-            });
-        }
-        if (record.lastUrl === null) {
-            // No frameNavigated arrived (e.g. a fast 204 or already-stopped load). Trust the pre-navigate
-            // validator: the requested URL was loopback, so allow capture against that origin.
-            record.originAllowed = true;
-            record.lastOriginOnly = expectedOrigin;
-        }
-    }
-    screenshot = async (sessionId) => {
-        return this.runSessionAction(sessionId, async (record) => {
-            this.requireOriginAllowed(record, "Screenshot");
-            this.touch(record);
-            const result = await record.client.send("Page.captureScreenshot", { format: "png" }, record.cdpSessionId);
-            // Defence in depth against the frameNavigated race: if a redirect arrived while
-            // captureScreenshot was in flight, the listener has now run and flipped originAllowed.
-            // Discard the bytes rather than hand evidence from a non-loopback origin to the caller.
-            if (!record.originAllowed) {
-                throw new BrowserToolError("ORIGIN_NOT_ALLOWED", "Screenshot blocked: origin drifted off-loopback during capture.");
-            }
-            const bytes = Buffer.from(result.data, "base64");
-            if (bytes.length > MAX_SCREENSHOT_BYTES) {
-                throw new BrowserToolError("SCREENSHOT_TOO_LARGE", "Screenshot exceeds the size limit.");
-            }
-            record.captureSeq += 1;
-            const seq = record.captureSeq;
-            const capturedAt = this.nowMs();
-            // M1: evict the oldest entry if the cap is reached (Map is insertion-ordered).
-            if (record.pendingScreenshots.size >= MAX_PENDING_SCREENSHOTS) {
-                const oldest = record.pendingScreenshots.keys().next().value;
-                if (oldest !== undefined)
-                    record.pendingScreenshots.delete(oldest);
-            }
-            record.pendingScreenshots.set(seq, { seq, viewportPx: DEFAULT_VIEWPORT, bytes, capturedAt });
-            this.emitRecord(record, "screenshot-captured", {
-                captureSeq: seq,
-                persisted: false,
-                viewportPx: DEFAULT_VIEWPORT,
-            }, capturedAt);
-            return { seq, viewportPx: DEFAULT_VIEWPORT, dataBase64: result.data, persisted: false };
-        });
-    };
-    applyScreenshot = async (sessionId, captureSeq) => this.runSessionAction(sessionId, (record) => {
-        const pending = record.pendingScreenshots.get(captureSeq);
-        if (pending === undefined) {
-            throw new BrowserToolError("NO_PENDING_SCREENSHOT", "No pending screenshot for this sequence.");
-        }
-        this.touch(record);
-        const name = `browser-${String(pending.seq)}.png`;
-        const written = writeSideFile(this.opts.evidenceDir, record.runId, name, pending.bytes, this.opts.sideFileOptions);
-        const screenshot = {
-            seq: pending.seq,
-            viewportPx: pending.viewportPx,
-            path: written.relativePath,
-            sha256: written.sha256,
-            bytes: written.bytes,
-            capturedAt: pending.capturedAt,
-        };
-        record.screenshots.push(screenshot);
-        record.pendingScreenshots.delete(captureSeq);
-        this.emitRecord(record, "screenshot-captured", {
-            captureSeq,
-            persisted: true,
-            viewportPx: pending.viewportPx,
-            path: written.relativePath,
-            sha256: written.sha256,
-            bytes: written.bytes,
-        });
-        return {
-            seq: pending.seq,
-            viewportPx: pending.viewportPx,
-            persisted: true,
-            path: written.relativePath,
-            sha256: written.sha256,
-            bytes: written.bytes,
-        };
-    });
-    content = async (sessionId) => {
-        return this.runSessionAction(sessionId, async (record) => {
-            this.requireOriginAllowed(record, "Content capture");
-            this.touch(record);
-            const doc = await record.client.send("DOM.getDocument", {}, record.cdpSessionId);
-            const html = await record.client.send("DOM.getOuterHTML", { nodeId: doc.root.nodeId }, record.cdpSessionId);
-            // Defence in depth against the frameNavigated race during the DOM.getOuterHTML RPC.
-            if (!record.originAllowed) {
-                throw new BrowserToolError("ORIGIN_NOT_ALLOWED", "Content capture blocked: origin drifted off-loopback during capture.");
-            }
-            const raw = html.outerHTML;
-            if (Buffer.byteLength(raw, "utf8") > MAX_CONTENT_BYTES) {
-                throw new BrowserToolError("CONTENT_TOO_LARGE", "Page content exceeds the size limit.");
-            }
-            const redacted = this.redactor(raw);
-            const redactedHtml = typeof redacted === "string" ? redacted : raw;
-            const byteLength = Buffer.byteLength(redactedHtml, "utf8");
-            if (byteLength > MAX_CONTENT_BYTES) {
-                throw new BrowserToolError("CONTENT_TOO_LARGE", "Page content exceeds the size limit.");
-            }
-            record.captureSeq += 1;
-            const seq = record.captureSeq;
-            record.contentCaptures.push({ seq, byteLength, capturedAt: this.nowMs(), redactedHtml });
-            this.emitRecord(record, "page-content-captured", { captureSeq: seq, byteLength });
-            return { seq, byteLength, redactedHtml };
-        });
-    };
-    listSessionIds = () => [...this.sessions.keys()];
-    hasSession = (sessionId) => {
-        const record = this.sessions.get(sessionId);
-        return record !== undefined && !record.closed;
-    };
-    dispose = async () => {
-        for (const id of [...this.sessions.keys()]) {
-            const record = this.sessions.get(id);
-            if (record !== undefined) {
-                await this.closeRecord(record, "process-exit", true);
-            }
-        }
-    };
-    subscribe = (sessionId, listener) => {
-        if (!this.hasSession(sessionId)) {
-            return () => undefined;
-        }
-        let set = this.subscribers.get(sessionId);
-        if (set === undefined) {
-            set = new Set();
-            this.subscribers.set(sessionId, set);
-        }
-        const targetSet = set;
-        targetSet.add(listener);
-        return () => {
-            targetSet.delete(listener);
-            if (targetSet.size === 0)
-                this.subscribers.delete(sessionId);
-        };
-    };
-    counterAccessor = () => this.counters;
-    requireRecord(sessionId) {
-        const record = this.sessions.get(sessionId);
-        if (record === undefined || record.closed) {
-            throw new BrowserToolError("SESSION_NOT_FOUND", "Browser session not found.");
-        }
-        return record;
-    }
-    requireOriginAllowed(record, subject) {
-        if (record.originAllowed)
-            return;
-        throw new BrowserToolError("ORIGIN_NOT_ALLOWED", `${subject} blocked: current origin is not on the loopback interface.`);
-    }
-    touch(record) {
-        record.lastTouchedMs = this.nowMs();
-        if (record.idleTimer !== undefined)
-            clearTimeout(record.idleTimer);
-        record.idleTimer = setTimeout(() => {
-            void this.closeRecord(record, "idle-timeout", true).catch(() => undefined);
-        }, this.idleTtlMs).unref();
-    }
-    fanout(event) {
-        const set = this.subscribers.get(event.sessionId);
-        if (set === undefined)
-            return;
-        for (const listener of [...set]) {
-            try {
-                listener(event);
-            }
-            catch {
-                // A subscriber throwing must not stop fan-out.
-            }
-        }
-    }
-    frameNavigatedListener(record) {
-        return (event) => {
-            if (event.method !== "Page.frameNavigated")
-                return;
-            this.handleFrameNavigated(record, event.params);
-        };
-    }
-    handleFrameNavigated(record, params) {
-        if (isSubframeNavigation(params))
-            return;
-        const url = mainFrameUrl(params);
-        if (url === null)
-            return;
-        record.lastUrl = url;
-        const originOnly = safeOrigin(url);
-        if (this.isExpectedOrigin(record, url, originOnly)) {
-            record.originAllowed = true;
-            record.lastOriginOnly = originOnly;
-            return;
-        }
-        this.rejectFrameNavigation(record, originOnly);
-    }
-    isExpectedOrigin(record, url, originOnly) {
-        return isLoopbackUrl(url) && originOnly !== null && originOnly === record.expectedOriginOnly;
-    }
-    rejectFrameNavigation(record, originOnly) {
-        record.originAllowed = false;
-        record.lastOriginOnly = originOnly;
-        // Best-effort stop loading; ignore the rejection — the next caller will see
-        // ORIGIN_NOT_ALLOWED on screenshot/content anyway.
-        void record.client.send("Page.stopLoading", {}, record.cdpSessionId).catch(() => undefined);
-        this.emitErrorRecord(record, "ORIGIN_NOT_ALLOWED", "Navigation drifted away from the requested loopback origin.");
-    }
-}
-export function createBrowserSessionManager(options) {
-    return new BrowserSessionManagerImpl(options);
-}
+// Re-export shim: the browser session manager lives in @oscharko-dev/keiko-tools (issue #162,
+// ADR-0019). All existing import sites (`from "../tools/browser/session.js"`) keep resolving
+// unchanged via this barrel.
+export { createBrowserSessionManager, } from "@oscharko-dev/keiko-tools";