firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/native/drivers/playwright.js

@@ -0,0 +1,600 @@
+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;
+};
+/**
+ * playwright.v1 driver (Plan20 spec 3.3).
+ *
+ * Playwright is customer-provided: it is resolved from the approved customer
+ * root with createRequire(<root>/package.json) and loaded with a dynamic import
+ * of the resolved file URL. Firedrill never bundles, installs or downloads it
+ * (nor its browsers). describe() reports unavailable, with the reason, when the
+ * package cannot be resolved; prepare() also fails clearly when the browser
+ * binary cannot be launched. The browser used is Chromium, headless.
+ *
+ * Flow module: an approved file inside the root, pinned by ctx.adapterSha256,
+ * re-hashed before import and imported via its file URL (digest in the query so
+ * a changed file is never served from the module cache). It exports
+ *   login(page, identity)  identity = target-auth PlaywrightLoginAccessor | null
+ *   send(page, step)       step = target-visible view only; returns observed output
+ *   reset(page)            optional; resets client-side view state
+ * as named exports or as properties of the default export.
+ *
+ * One browser context per drill session (fresh cookies/storage). A context reset
+ * or the flow's reset() is reported as a browser-context reset with
+ * backend_reset:false; it is never reported as a backend reset.
+ *
+ * Screenshots are off unless the approved plan turns them on (`screenshots`).
+ * Then each one is the visible page as a PNG, taken with every form field and
+ * the plan's selectors blacked out first (screenshots.ts), re-encoded without
+ * metadata (png.ts) and capped in count. Masking is not secret detection: other
+ * text on screen is captured as shown, so flows should keep secrets off screen.
+ * Each drill records that capture was requested and whether it can run
+ * (`capture.requested`); a step whose capture produced no image records why
+ * (`capture.unavailable`), never the error or page content.
+ * With `screenshots.frames` the driver also captures masked frames while each
+ * step's send() runs, one per interval and at most `max_per_step` per step,
+ * with animations left running so the flow's page is not changed. They are
+ * captured frames, not a video. A frame that produced no image, and every
+ * interval past the step's count, is counted with its reason.
+ * With `trace: "sanitized-actions"` the flow gets its page through a recording
+ * view (action-trace.ts) that keeps only operation kinds, outcomes and times.
+ * Playwright video, Playwright trace files and HAR are never used: they would
+ * carry unmasked frames, input values or network bodies.
+ * The flow runs in the companion process as trusted, user-approved local code.
+ * A step whose send() timed out leaves the page in an unknown state, so that
+ * session's context is closed and later steps in it fail explicitly.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CliError } from '../../http.js';
+import { CAPTURE_SCHEMA, FRAME_OMISSION_REASONS, NATIVE_ERRORS, nativeError } from '../contracts.js';
+import { metadataFreePng } from '../png.js';
+import { MASK_COLOR, maskingPolicy } from '../screenshots.js';
+import { ActionTrace } from './action-trace.js';
+import { sha256Hex } from '../canonical.js';
+import { insideRoot } from '../roots.js';
+import { playwrightLogin } from '../target-auth.js';
+import { DRIVER_ERRORS, OwnDigest, StepRecorder, clockOf, driverBounds, driverPlanFor, emit, emitTrace, loopbackBase, loopbackTarget, planError, precheck, readPinned, rootPath, serviceHandle, stepAbort, stepInput, stepTimeoutMs, unattested, } from './types.js';
+/** Playwright's own version from the project's installed package, or null when it cannot be read. */
+function playwrightVersion(root) {
+    try {
+        const manifest = createRequire(path.join(root, 'package.json')).resolve('playwright/package.json');
+        const version = JSON.parse(readFileSync(manifest, 'utf8'))?.version;
+        const match = typeof version === 'string' ? /^(\d+)\.(\d+)\./.exec(version) : null;
+        return match ? [Number(match[1]), Number(match[2])] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Screenshot masking with a fixed mask color needs Playwright 1.35 or later. */
+const MASK_MIN_VERSION = [1, 35];
+/** Resolve the customer's Playwright entry from a root, or null when absent. */
+export function resolvePlaywright(root) {
+    if (!root || !path.isAbsolute(root))
+        return null;
+    try {
+        return createRequire(path.join(root, 'package.json')).resolve('playwright');
+    }
+    catch {
+        return null;
+    }
+}
+function browserTypeFrom(module) {
+    const record = module;
+    const candidate = (record?.chromium ?? record?.default?.chromium);
+    return candidate && typeof candidate.launch === 'function' ? candidate : null;
+}
+function flowFrom(module) {
+    const record = module;
+    const source = (typeof record?.send === 'function' ? record : record?.default);
+    if (!source || typeof source.login !== 'function' || typeof source.send !== 'function')
+        return null;
+    if (source.reset !== undefined && typeof source.reset !== 'function')
+        return null;
+    return {
+        login: source.login,
+        send: source.send,
+        reset: source.reset,
+    };
+}
+const BROWSER_ENV = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TMP', 'TEMP', 'SystemRoot', 'USERPROFILE', 'LOCALAPPDATA', 'XDG_RUNTIME_DIR'];
+function browserEnv(env) {
+    const output = {};
+    for (const name of BROWSER_ENV)
+        if (typeof env[name] === 'string')
+            output[name] = env[name];
+    return output;
+}
+class FlowAborted extends Error {
+}
+class FlowTimeout extends Error {
+}
+/** Frames wait in memory until their step ends: at most this many bytes of them per step. */
+const FRAME_STEP_MAX_BYTES = 16 * 1024 * 1024;
+/** Wait `ms`, ending early when `signal` aborts; true when the whole wait passed. */
+function pause(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve(false);
+            return;
+        }
+        const done = (passed) => { clearTimeout(timer); signal.removeEventListener('abort', aborted); resolve(passed); };
+        const aborted = () => done(false);
+        const timer = setTimeout(() => done(true), ms);
+        signal.addEventListener('abort', aborted, { once: true });
+    });
+}
+function withFrames(capture, frames) {
+    return capture && frames ? { ...capture, frames } : capture;
+}
+function raceAbort(work, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            void work.catch(() => undefined);
+            reject(new FlowAborted());
+            return;
+        }
+        const onAbort = () => reject(new FlowAborted());
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+async function withTimeout(work, ms, signal) {
+    if (signal.aborted)
+        throw new FlowAborted();
+    const timer = AbortSignal.timeout(Math.max(1, ms));
+    const combined = AbortSignal.any([timer, signal]);
+    try {
+        return await raceAbort(Promise.resolve().then(() => { if (combined.aborted)
+            throw new FlowAborted(); return work(); }), combined);
+    }
+    catch (error) {
+        if (error instanceof FlowAborted && timer.aborted)
+            throw new FlowTimeout();
+        throw error;
+    }
+}
+/** A timed-out allocation may still return a handle. Keep its original cleanup
+ * obligation until that exact handle has closed; never turn timeout into absence. */
+async function acquire(work, ms, signal, pending) {
+    if (signal.aborted)
+        throw new FlowAborted();
+    let finish;
+    const obligation = new Promise(resolve => { finish = resolve; });
+    pending.add(obligation);
+    void obligation.then(() => pending.delete(obligation), () => undefined);
+    const original = Promise.resolve().then(() => { if (signal.aborted)
+        throw new FlowAborted(); return work(); });
+    try {
+        const handle = await withTimeout(() => original, ms, signal);
+        finish();
+        return handle;
+    }
+    catch (error) {
+        const cleanup = original.then(handle => handle.close(), () => undefined);
+        finish(cleanup);
+        throw error;
+    }
+}
+function errorSummary(error) {
+    if (error instanceof Error)
+        return { name: error.name, message: error.message };
+    return { name: typeof error };
+}
+export class PlaywrightDriver {
+    profile = 'playwright.v1';
+    plan;
+    prepared = null;
+    sessions = new Set();
+    pendingCleanup = new Set();
+    cleanupMs = 60_000;
+    disposing = false;
+    lifecycle = new AbortController();
+    constructor(options = {}) { this.plan = options.plan ?? null; }
+    async describe() {
+        const plan = this.plan;
+        const roots = !plan ? [] : plan.driver.profile === 'playwright.v1'
+            ? plan.roots.filter((root) => root.alias === plan.driver.root_alias)
+            : plan.roots;
+        if (!roots.length)
+            return { available: false, reason: 'No approved project root is available to resolve the customer-provided Playwright package from.' };
+        for (const root of roots)
+            if (resolvePlaywright(root.path))
+                return { available: true, reason: null };
+        return { available: false,
+            reason: 'Playwright is not installed in the approved project root. Firedrill does not install or bundle it; add it to the project to run browser drills.' };
+    }
+    async prepare(ctx) {
+        ctx = { ...ctx, signal: AbortSignal.any([ctx.signal, this.lifecycle.signal]) };
+        const plan = driverPlanFor(ctx, 'playwright.v1');
+        if (this.prepared)
+            throw planError('The browser driver is already prepared; a second browser was not started.');
+        const bounds = driverBounds(ctx);
+        this.cleanupMs = bounds.flowSetupMs;
+        if (this.disposing || this.pendingCleanup.size)
+            throw planError('The previous browser startup has unresolved cleanup. No replacement was started.');
+        const root = rootPath(ctx, plan.root_alias);
+        const resolved = resolvePlaywright(root);
+        if (!resolved)
+            throw nativeError('driver_unavailable', 'Playwright is not installed in the approved project root, so no browser was started. Firedrill does not install it.');
+        let browserType = null;
+        try {
+            browserType = browserTypeFrom(await withTimeout(() => import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href)), bounds.flowSetupMs, ctx.signal));
+        }
+        catch {
+            browserType = null;
+        }
+        if (!browserType)
+            throw nativeError('driver_unavailable', 'The project\'s Playwright package could not be loaded, so no browser was started.');
+        const flowPath = await withTimeout(() => insideRoot(root, plan.flow), bounds.flowSetupMs, ctx.signal);
+        const pinned = await withTimeout(() => readPinned(flowPath, ctx.adapterSha256), bounds.flowSetupMs, ctx.signal);
+        let flow = null;
+        try {
+            flow = flowFrom(await withTimeout(() => import(__rewriteRelativeImportExtension(`${pathToFileURL(flowPath).href}?sha256=${pinned.sha256}`)), bounds.flowSetupMs, ctx.signal));
+        }
+        catch {
+            flow = null;
+        }
+        if (!flow)
+            throw planError('The approved browser flow could not be loaded or does not export login(page, identity) and send(page, step), so no browser was started.');
+        emit(ctx, 'state.observed', { type: 'adapter.verified', profile: this.profile, adapter_sha256: new OwnDigest(pinned.sha256) });
+        const handle = serviceHandle(ctx, plan.service_alias);
+        const base = loopbackBase(handle.url, plan.service_alias);
+        const start = loopbackTarget(base, plan.start_path, plan.service_alias);
+        let browser;
+        // Playwright's own signal handlers close the browser and then exit the process (130) on the first Ctrl-C,
+        // which would skip the companion's stop, signed close, local-run close and owned-group sweep. The companion
+        // owns signals and closes the browser itself (retainClose / dispose).
+        try {
+            browser = await acquire(() => browserType.launch({ headless: true, env: browserEnv(ctx.env), timeout: bounds.flowSetupMs,
+                handleSIGINT: false, handleSIGTERM: false, handleSIGHUP: false }), bounds.flowSetupMs, ctx.signal, this.pendingCleanup);
+        }
+        catch {
+            throw nativeError('driver_unavailable', 'The local Playwright browser could not be started (its browser binary may not be installed in this project), so no browser drill ran.');
+        }
+        if (this.disposing || ctx.signal.aborted) {
+            await this.retainClose(browser);
+            throw nativeError('driver_unavailable', 'Browser startup was cancelled. No browser session was opened.');
+        }
+        // Screenshots only with the approved policy and a Playwright that can apply it; never an unmasked image.
+        // One record per drill says capture was requested and whether it can run (selector count, never selectors).
+        let masking = null;
+        if (plan.screenshots) {
+            const approved = maskingPolicy(plan.screenshots);
+            const version = playwrightVersion(root);
+            const available = version !== null
+                && (version[0] > MASK_MIN_VERSION[0] || (version[0] === MASK_MIN_VERSION[0] && version[1] >= MASK_MIN_VERSION[1]));
+            const frames = plan.screenshots.frames ?? null;
+            if (available)
+                masking = { selectors: approved.policy.selectors, sha256: approved.sha256, frames };
+            emit(ctx, 'state.observed', { type: 'capture.requested', schema: CAPTURE_SCHEMA, capture: 'screenshot',
+                masking_policy_sha256: new OwnDigest(approved.sha256), selector_count: approved.policy.selectors.length,
+                max_per_session: bounds.maxScreenshotsPerSession, available,
+                // Masked frames while each step runs (null when the plan takes none). Frames count toward max_per_session.
+                frame_interval_ms: frames?.interval_ms ?? null, max_frames_per_step: frames?.max_per_step ?? null,
+                // Playwright older than 1.35, or its version could not be read.
+                reason: available ? null : 'driver_unsupported' });
+        }
+        this.prepared = { browser, flow, base, start, flowSha256: pinned.sha256, masking, trace: plan.trace === 'sanitized-actions' };
+    }
+    async openSession(ctx, sessionKey) {
+        ctx = { ...ctx, signal: AbortSignal.any([ctx.signal, this.lifecycle.signal]) };
+        const prepared = this.prepared;
+        if (!prepared || this.disposing)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The browser driver was not prepared, so no session was opened.');
+        if (!sessionKey)
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The session key is empty, so no session was opened.');
+        const bounds = driverBounds(ctx);
+        let context = null;
+        let trace = null;
+        const accessor = playwrightLogin(ctx.identity);
+        try {
+            context = await acquire(() => prepared.browser.newContext({ baseURL: prepared.base.origin, acceptDownloads: false }), bounds.flowSetupMs, ctx.signal, this.pendingCleanup);
+            const page = await withTimeout(() => context.newPage(), bounds.flowSetupMs, ctx.signal);
+            await withTimeout(() => page.goto(prepared.start.href, { timeout: bounds.flowSetupMs, waitUntil: 'load' }), bounds.flowSetupMs, ctx.signal);
+            // The approved trace records the flow's own calls, from login on; the driver's navigation above is not one.
+            // One capture per browser session.
+            trace = prepared.trace ? new ActionTrace(clockOf(ctx), (segment) => { emitTrace(ctx, segment); return true; }) : null;
+            const flowPage = trace ? trace.view(page) : page;
+            await withTimeout(() => prepared.flow.login(flowPage, accessor), bounds.flowSetupMs, ctx.signal);
+            if (this.disposing || ctx.signal.aborted)
+                throw new FlowAborted();
+            trace?.cut();
+            emit(ctx, 'state.observed', {
+                type: 'browser.context.fresh', scope: 'browser-context', session_key: sessionKey, backend_reset: false,
+                login: accessor ? 'synthetic-credentials' : 'none',
+            });
+            const session = new PlaywrightSession(ctx, prepared.flow, context, page, flowPage, trace, sessionKey, prepared.masking, () => this.sessions.delete(session));
+            this.sessions.add(session);
+            emit(ctx, 'action.observed', { type: 'session.opened', profile: this.profile, session_key: sessionKey });
+            return session;
+        }
+        catch (error) {
+            trace?.end(ctx.signal.aborted ? 'cancelled' : 'driver_failed');
+            if (context)
+                await this.retainClose(context);
+            emit(ctx, 'driver.failed', { type: 'browser.session_failed', session_key: sessionKey,
+                cause: error instanceof FlowTimeout ? 'timeout' : 'error' });
+            throw new CliError(DRIVER_ERRORS.session_failed, 'The browser session could not be opened (start page or flow login did not finish), so no step was sent.');
+        }
+        finally {
+            accessor?.dispose();
+        }
+    }
+    /** SHA-256 of the HTML the approved start path served, loaded in a throwaway browser context (closed after). */
+    async readinessProbe(ctx) {
+        ctx = { ...ctx, signal: AbortSignal.any([ctx.signal, this.lifecycle.signal]) };
+        const prepared = this.prepared;
+        if (!prepared || this.disposing)
+            throw unattested('The browser driver was not prepared, so the start document cannot be attested. Nothing was claimed.');
+        const bounds = driverBounds(ctx);
+        let context = null;
+        try {
+            context = await acquire(() => prepared.browser.newContext({ baseURL: prepared.base.origin, acceptDownloads: false }), bounds.flowSetupMs, ctx.signal, this.pendingCleanup);
+            const page = await withTimeout(() => context.newPage(), bounds.flowSetupMs, ctx.signal);
+            await withTimeout(() => page.goto(prepared.start.href, { timeout: bounds.flowSetupMs, waitUntil: 'load' }), bounds.flowSetupMs, ctx.signal);
+            const html = await withTimeout(() => page.content(), bounds.flowSetupMs, ctx.signal);
+            if (typeof html !== 'string')
+                throw new Error('no document');
+            return { kind: 'browser_document', response_sha256: sha256Hex(Buffer.from(html, 'utf8')) };
+        }
+        catch {
+            throw unattested('The approved start page did not load in the local browser, so it cannot be attested. Nothing was claimed.');
+        }
+        finally {
+            if (context)
+                await this.retainClose(context);
+        }
+    }
+    async retainClose(handle) {
+        const close = Promise.resolve().then(() => handle.close());
+        this.pendingCleanup.add(close);
+        void close.then(() => this.pendingCleanup.delete(close), () => undefined);
+        await withTimeout(() => close, this.cleanupMs, new AbortController().signal).catch(() => undefined);
+    }
+    async dispose() {
+        this.disposing = true;
+        this.lifecycle.abort();
+        const prepared = this.prepared;
+        this.prepared = null;
+        // Close the browser concurrently: a stuck context must not prevent browser cleanup.
+        const work = [...this.sessions].map(session => session.close());
+        if (prepared)
+            work.push(this.retainClose(prepared.browser));
+        const results = await Promise.allSettled(work);
+        if (this.pendingCleanup.size)
+            await withTimeout(() => Promise.all([...this.pendingCleanup]), this.cleanupMs, new AbortController().signal);
+        if (results.some(result => result.status === 'rejected'))
+            throw new CliError(DRIVER_ERRORS.session_failed, 'Browser cleanup is not confirmed. Keep the original local execution for recovery.');
+    }
+}
+class PlaywrightSession {
+    sessionKey;
+    ctx;
+    flow;
+    context;
+    /** The real page: the driver's own captures use it. */
+    page;
+    /** What the flow gets: the page itself, or its recording view when the approved trace is on. */
+    flowPage;
+    trace;
+    onClose;
+    bounds;
+    /** The approved masking policy, or null when the plan captures no screenshots. */
+    masking;
+    /** Captures taken in this session, screenshots and frames together. */
+    screenshots = 0;
+    closed = false;
+    busy = false;
+    closing = null;
+    constructor(ctx, flow, context, page, flowPage, trace, sessionKey, masking, onClose) {
+        this.ctx = ctx;
+        this.flow = flow;
+        this.context = context;
+        this.page = page;
+        this.sessionKey = sessionKey;
+        this.onClose = onClose;
+        this.flowPage = flowPage;
+        this.trace = trace;
+        this.bounds = driverBounds(ctx);
+        this.masking = masking;
+    }
+    none(masking, unavailable) {
+        return { unavailable, masking_policy_sha256: masking.sha256, session_key: this.sessionKey };
+    }
+    /**
+     * The step's approved capture: the masked image, or why there is none (a
+     * reason only, never the error or page content); null when the plan captures
+     * no screenshots. Best-effort evidence only: skipped once the step is
+     * aborted, and raced against the abort with a short bound so a slow capture
+     * never turns a completed step into an interrupted one or leaves the session busy.
+     */
+    async capture(signal) {
+        return this.masking ? this.shoot(this.masking, signal, 'disabled') : null;
+    }
+    /**
+     * One masked capture: the step's screenshot after send() returned (animations
+     * settled, caret hidden), or a frame while it runs (`allow`: animations and
+     * the caret are left as they are, so the flow's page is not changed).
+     */
+    async shoot(masking, signal, motion) {
+        const none = (unavailable) => this.none(masking, unavailable);
+        if (this.closed)
+            return none('page_closed');
+        if (this.screenshots >= this.bounds.maxScreenshotsPerSession)
+            return none('session_limit');
+        if (signal.aborted)
+            return none('capture_failed');
+        try {
+            if (this.page.isClosed())
+                return none('page_closed');
+            this.screenshots += 1;
+            // Playwright paints the box of every element the selectors match before capture. A selector that
+            // matches nothing masks nothing (absent form fields are normal); an error while capturing or
+            // masking fails closed, with no image. Masking hides matching elements, not every sensitive value.
+            const mask = masking.selectors.map((selector) => this.page.locator(selector));
+            const bytes = await raceAbort(Promise.resolve(this.page.screenshot({ type: 'png', fullPage: false, scale: 'css', timeout: 2_000,
+                animations: motion, caret: motion === 'disabled' ? 'hide' : 'initial', mask, maskColor: MASK_COLOR })), AbortSignal.any([signal, AbortSignal.timeout(2_000)]));
+            if (!(bytes instanceof Uint8Array))
+                return none('capture_failed');
+            if (bytes.byteLength > this.bounds.maxAttachmentBytes * 8)
+                return none('image_too_large');
+            const png = metadataFreePng(bytes);
+            return png ? { png, masking_policy_sha256: masking.sha256, session_key: this.sessionKey } : none('image_unsupported');
+        }
+        catch {
+            return none('capture_failed');
+        }
+    }
+    /**
+     * Masked frames while the flow's send() runs (approved `screenshots.frames`):
+     * one per interval, at most `max_per_step` per step, each masked like the
+     * step's screenshot and counted toward the session's captures. A frame that
+     * produced no image is counted with its reason, and so is every interval past
+     * the step's count (`step_limit`), so the step says how much of it the frames
+     * cover. `stop()` lets a frame being taken finish (bounded like any capture)
+     * and hands the frames over once.
+     */
+    frames(signal) {
+        const masking = this.masking;
+        const plan = masking?.frames;
+        if (!masking || !plan)
+            return null;
+        const shots = [];
+        const reasons = new Set();
+        let omitted = 0, bytes = 0, handed = false;
+        const skip = (reason) => { omitted += 1; reasons.add(reason); };
+        const stopped = new AbortController();
+        const ticks = AbortSignal.any([signal, stopped.signal]);
+        const now = clockOf(this.ctx);
+        const running = (async () => {
+            while (await pause(plan.interval_ms, ticks)) {
+                if (shots.length >= plan.max_per_step) {
+                    skip('step_limit');
+                    continue;
+                }
+                const at = now();
+                const frame = await this.shoot(masking, signal, 'allow');
+                if (!('png' in frame)) {
+                    skip(frame.unavailable);
+                    continue;
+                }
+                if (bytes + frame.png.byteLength > FRAME_STEP_MAX_BYTES) {
+                    skip('evidence_capacity');
+                    continue;
+                }
+                bytes += frame.png.byteLength;
+                shots.push({ png: frame.png, masking_policy_sha256: frame.masking_policy_sha256, session_key: frame.session_key, at_ms: at });
+            }
+        })().catch(() => undefined);
+        return {
+            stop: async () => {
+                stopped.abort();
+                await running;
+                if (handed)
+                    return undefined;
+                handed = true;
+                return { shots, omitted, reasons: FRAME_OMISSION_REASONS.filter((reason) => reasons.has(reason)) };
+            },
+        };
+    }
+    async invoke(step, signal) {
+        const recorder = new StepRecorder(this.ctx, step);
+        if (this.closed)
+            return recorder.finish('failed', null, DRIVER_ERRORS.session_closed);
+        if (this.busy)
+            return recorder.finish('failed', null, DRIVER_ERRORS.step_unsupported);
+        const refused = precheck(step, this.sessionKey, ['message', 'task']);
+        if (refused)
+            return recorder.finish('failed', null, refused);
+        const input = stepInput(step);
+        const view = Object.freeze({
+            step_id: step.step_id, sequence: step.sequence, kind: input.kind, session_key: this.sessionKey,
+            text: input.kind === 'message' ? input.input : null,
+            input: input.kind === 'task' ? input.input : null,
+        });
+        recorder.record('action.observed', { type: 'target.exchange', direction: 'to_target', kind: input.kind, session_key: this.sessionKey, content: input.input });
+        const abort = stepAbort(this.ctx, signal, stepTimeoutMs(step, this.bounds));
+        if (abort.signal.aborted) {
+            abort.dispose();
+            return recorder.interrupted(abort.cause() ?? 'cancelled', false);
+        }
+        this.busy = true;
+        // Trace segments cut while this step runs are its own records, queued after its capture so frames keep their times.
+        this.trace?.attach((segment) => recorder.recordTrace(segment), abort.signal);
+        const frames = this.frames(abort.signal);
+        try {
+            const output = await raceAbort(Promise.resolve().then(() => this.flow.send(this.flowPage, view)), abort.signal);
+            // Frames end before the step's screenshot. The completed result is kept whether or not either produced an image.
+            const shots = await frames?.stop();
+            const capture = withFrames(await this.capture(abort.signal), shots);
+            recorder.record('action.observed', { type: 'target.exchange', direction: 'from_target', content: output }, undefined, capture);
+            this.trace?.cut();
+            return recorder.finish('completed', output, null);
+        }
+        catch (error) {
+            const shots = await frames?.stop();
+            if (error instanceof FlowAborted) {
+                // send() may still be acting on the page: no screenshot is taken and this context is retired. Frames
+                // taken before the stop are kept, recorded ahead of the cleanup so they keep their times.
+                const cause = abort.cause() ?? 'cancelled';
+                recorder.noteInterrupted(cause, true, this.masking ? withFrames(this.none(this.masking, 'capture_failed'), shots) : null);
+                recorder.record('state.observed', { type: 'browser.context.closing', scope: 'browser-context', backend_reset: false, reason: 'step interrupted' });
+                this.trace?.end('cancelled');
+                await this.close();
+                recorder.record('state.observed', { type: 'browser.context.closed', scope: 'browser-context', backend_reset: false, reason: 'step interrupted' });
+                return recorder.interrupted(cause, true);
+            }
+            const capture = withFrames(await this.capture(abort.signal), shots);
+            recorder.record('action.observed', { type: 'flow.error', error: errorSummary(error) }, undefined, capture);
+            this.trace?.cut();
+            return recorder.interrupted('thrown', true);
+        }
+        finally {
+            this.trace?.detach();
+            this.busy = false;
+            abort.dispose();
+        }
+    }
+    /** Run the flow's optional reset(page). Client-side only; never a backend reset. */
+    async resetLocal() {
+        const result = (applied, error_code) => {
+            emit(this.ctx, 'state.observed', { type: 'browser.context.reset', scope: 'browser-context', session_key: this.sessionKey,
+                applied, backend_reset: false, error_code });
+            return { scope: 'browser-context', applied, backend_reset: false, error_code };
+        };
+        if (this.closed)
+            return result(false, DRIVER_ERRORS.session_closed);
+        const reset = this.flow.reset;
+        if (!reset)
+            return result(false, NATIVE_ERRORS.state_unsupported);
+        try {
+            await withTimeout(() => reset(this.flowPage), this.bounds.flowSetupMs, this.ctx.signal);
+            return result(true, null);
+        }
+        catch {
+            return result(false, DRIVER_ERRORS.session_failed);
+        }
+        finally {
+            this.trace?.cut();
+        }
+    }
+    async close() {
+        if (this.closing)
+            return withTimeout(() => this.closing, this.bounds.flowSetupMs, new AbortController().signal);
+        this.closed = true;
+        // The capture ends with the session, before the context closes, so calls the close ends are not recorded as failures.
+        this.trace?.end();
+        this.closing = Promise.resolve().then(() => this.context.close());
+        void this.closing.then(() => this.onClose(), () => undefined);
+        await withTimeout(() => this.closing, this.bounds.flowSetupMs, new AbortController().signal);
+    }
+}