e2e 0.21.0 → 0.21.1

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.21.0"}
+{"version":"0.21.1"}

package/dist/agent/executor.d.ts

@@ -117,6 +117,13 @@ export interface ExecutorObservation {
     readonly text: string;
     readonly truncated: boolean;
     readonly viewport: ViewportSize;
+    /**
+     * Whether an on-screen keyboard is showing, as the engine measured it apart
+     * from the tree; `false` when it measured none. Absent only when the engine
+     * did not measure it; the tree's `keyboard` and `key` nodes, or a
+     * screenshot, are then the evidence.
+     */
+    readonly keyboardVisible?: boolean;
     /**
      * The current location as path and query, redacted, when the engine
      * reports one. Absent on engines without a location (a device screen).

package/dist/agent/observation-feed.js

@@ -132,6 +132,7 @@ export class ObservationFeed {
             ...metadata,
             text: observation.text,
             truncated: observation.truncated,
+            ...(observation.keyboardVisible === undefined ? {} : { keyboardVisible: observation.keyboardVisible }),
             ...(options.tree === true ? { tree: projectTree(observation.tree, this.runtime.app.base?.origin) } : {}),
             ...pixels,
         };

package/dist/agent/observation.d.ts

@@ -11,6 +11,8 @@ export type AgentObservation = AgentObservationMetadata & ({
     readonly parents: ReadonlyMap<string, string>;
     readonly tree: RedactedNode;
     readonly truncated: boolean;
+    /** The engine's measured keyboard state; `false` when it measured none, absent only when it did not measure. */
+    readonly keyboardVisible?: boolean | undefined;
     readonly pixels?: ExecutorPixels | undefined;
     readonly pixelsWithheld?: PixelsWithheld | undefined;
 } | {

package/dist/agent/observation.js

@@ -94,6 +94,7 @@ export function prepareObservation(observation, options) {
         parents,
         tree,
         truncated,
+        ...(observation.keyboardVisible === undefined ? {} : { keyboardVisible: observation.keyboardVisible }),
         ...(pixels.cleared === undefined ? {} : { pixels: pixels.cleared }),
         ...(pixels.withheld === undefined ? {} : { pixelsWithheld: pixels.withheld }),
     };

package/dist/cli/bin.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { unsupportedRuntimeMessage } from '../internal/node-version.js';
+import { ignoreBrokenPipes } from './broken-pipe.js';
 // Checked before the CLI module loads: that module and its dependencies are
 // what an old runtime would fail on, with a stack trace instead of a sentence.
 const unsupported = unsupportedRuntimeMessage();
@@ -7,5 +8,6 @@ if (unsupported !== undefined) {
     process.stderr.write(`${unsupported}\n`);
     process.exit(2);
 }
+ignoreBrokenPipes([process.stdout, process.stderr]);
 const { main } = await import('./index.js');
 await main(process.argv);

package/dist/cli/broken-pipe.d.ts

@@ -0,0 +1,10 @@
+import type { Writable } from 'node:stream';
+/**
+ * A reader that stops early (`e2e --help | head -1`) closes the pipe, and the
+ * next write fails with EPIPE, an `error` event that kills the process with a
+ * stack trace when nothing listens. EPIPE is dropped instead: output nobody
+ * reads is discarded and the command finishes as it would have, teardown and
+ * exit code included. Any other error still throws, unless another listener
+ * (the MCP server's, on its protocol pipe) handles it.
+ */
+export declare function ignoreBrokenPipes(streams: readonly Writable[]): void;

package/dist/cli/broken-pipe.js

@@ -0,0 +1,17 @@
+/**
+ * A reader that stops early (`e2e --help | head -1`) closes the pipe, and the
+ * next write fails with EPIPE, an `error` event that kills the process with a
+ * stack trace when nothing listens. EPIPE is dropped instead: output nobody
+ * reads is discarded and the command finishes as it would have, teardown and
+ * exit code included. Any other error still throws, unless another listener
+ * (the MCP server's, on its protocol pipe) handles it.
+ */
+export function ignoreBrokenPipes(streams) {
+    for (const stream of streams) {
+        stream.on('error', (error) => {
+            if (error.code === 'EPIPE' || stream.listenerCount('error') > 1)
+                return;
+            throw error;
+        });
+    }
+}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import { Argument, Command, CommanderError, InvalidArgumentError, Option } from
 import picocolors from 'picocolors';
 import { detectPackageManager, execCommand, runScriptCommand } from '../internal/package-manager.js';
 import { packageVersion } from '../internal/package-version.js';
+import { MAX_TIMER_MS } from '../internal/time.js';
 import { classifyError, exitCodeForCategory } from '../internal/errors.js';
 import { list } from '../runner.js';
 import { run } from '../run/runner.js';
@@ -33,7 +34,7 @@ import { skillTopics } from './skill.js';
 import { watchSession } from './watch.js';
 import { telemetry as telemetryCommand, TELEMETRY_ACTIONS } from './telemetry.js';
 import { wordmarkBanner } from './wordmark.js';
-/** An integer of at least one, for `--max-failures` and `--max-duration`. */
+/** An integer of at least one, for `--max-failures` and `--repeat-each`. */
 function parsePositiveInt(value) {
     const parsed = Number(value);
     if (!Number.isSafeInteger(parsed) || parsed < 1)
@@ -75,7 +76,7 @@ function parseShard(value) {
     }
     return { index, total };
 }
-/** An integer inside a closed range, for the explore budgets. */
+/** An integer inside a closed range, for the explore budgets and `--max-duration`. */
 function parseBoundedInt(bounds) {
     return (value) => {
         const parsed = Number(value);
@@ -462,7 +463,7 @@ function createProgram(version, telemetry) {
         .option('--workers <n>', 'parallel workers (default: from the config)', parseNonNegativeInt)
         .option('--retries <n>', 'retries per failing test (default: from the config)', parseNonNegativeInt)
         .option('--max-failures <n>', 'stop the run once this many tests have failed; the rest are skipped', parsePositiveInt)
-        .option('--max-duration <ms>', 'stop the run once it has spent this many milliseconds running tests; the rest are skipped (default: maxDuration in the config)', parsePositiveInt)
+        .option('--max-duration <ms>', 'stop the run once it has spent this many milliseconds running tests; the rest are skipped (default: maxDuration in the config)', parseBoundedInt({ min: 1, max: MAX_TIMER_MS }))
         .option('--repeat-each <n>', 'run every selected test this many times, each run its own result (pair with --no-cache to exercise the model each time)', parsePositiveInt)
         .option('--no-cache', 'run with the replay cache off, whatever the config says')
         .option('--strict-cache', 'fail a step whose recording no longer replays (REPLAY_STALE) instead of handing it to the agent; never writes the cache')

package/dist/cli/init/sibling-versions.json

@@ -1 +1 @@
-{"@e2e-dev/web":"0.15.0","@e2e-dev/mobile":"0.12.1"}
+{"@e2e-dev/web":"0.15.1","@e2e-dev/mobile":"0.12.2"}

package/dist/cli/run-output.d.ts

@@ -5,7 +5,7 @@
  * through a `RunnerOutput`, redacted, until the process exits; only the list
  * reporter writes to the terminal past it.
  */
-import { RunnerOutput } from '../run/process-output.ts';
+import { type RunnerOutput } from '../run/process-output.ts';
 /**
  * Takes over `process.stdout` and `process.stderr` for the rest of the
  * process, once: a reporter the run stopped waiting for, or a timer the

package/dist/cli/run-output.js

@@ -5,14 +5,8 @@
  * through a `RunnerOutput`, redacted, until the process exits; only the list
  * reporter writes to the terminal past it.
  */
-import { RunnerOutput } from '../run/process-output.js';
+import { claimProcessOutput } from '../run/process-output.js';
 import { processSecrets } from '../run/secrecy.js';
-/**
- * Encodings in which a string spells bytes rather than text: the write puts
- * those bytes on the terminal, so they are what is redacted. A string in any
- * other encoding is the text itself, redacted and written as UTF-8.
- */
-const BYTE_ENCODINGS = new Set(['hex', 'base64', 'base64url']);
 /** The process's claimed output, once claimed: the wrappers stay for the rest of the process. */
 let claimed;
 /**
@@ -26,19 +20,7 @@ let claimed;
 export function claimRunnerOutput() {
     if (claimed !== undefined)
         return claimed;
-    const streams = { stdout: process.stdout, stderr: process.stderr };
-    const terminal = {
-        stdout: streams.stdout.write.bind(streams.stdout),
-        stderr: streams.stderr.write.bind(streams.stderr),
-    };
-    const output = new RunnerOutput(terminal, processSecrets);
-    for (const name of ['stdout', 'stderr']) {
-        streams[name].write = ((chunk, encoding, callback) => {
-            const done = typeof encoding === 'function' ? encoding : callback;
-            const bytes = typeof chunk === 'string' && typeof encoding === 'string' && BYTE_ENCODINGS.has(encoding);
-            return output.write(name, bytes ? Buffer.from(chunk, encoding) : chunk, done);
-        });
-    }
+    const output = claimProcessOutput(processSecrets);
     process.once('exit', () => output.end());
     claimed = output;
     return output;

package/dist/engine/index.d.ts

@@ -563,6 +563,13 @@ export interface EngineSnapshot {
      * read whole.
      */
     readonly truncated?: boolean;
+    /**
+     * Whether an on-screen keyboard is showing, as the engine measured it apart
+     * from `root`: a platform can raise a keyboard the tree lists only in part,
+     * or not at all. Set `false` when it measured none, and omit it only when
+     * the engine did not measure it; consumers then fall back to the tree.
+     */
+    readonly keyboardVisible?: boolean;
     /**
      * Semantic capture timed out. Return only the stable root reference, with no other fields,
      * and fresh pixels whose masking was proven independently of the failed

package/dist/engine/session.js

@@ -355,6 +355,7 @@ export function createEngineSession(options) {
                 kind: 'semantic',
                 tree: stampRevision(snapshot.root, minted),
                 truncated: snapshot.truncated === true,
+                ...(snapshot.keyboardVisible === undefined ? {} : { keyboardVisible: snapshot.keyboardVisible }),
                 ...(snapshot.pixels === undefined ? {} : { pixels: snapshot.pixels }),
             };
             showScreen(observation);

package/dist/engine/surface.d.ts

@@ -32,6 +32,8 @@ export type Observation = ObservationMetadata & ({
     readonly kind: 'semantic';
     readonly tree: SemanticNode;
     readonly truncated: boolean;
+    /** The engine's measured keyboard state (`EngineSnapshot.keyboardVisible`); `false` when it measured none, absent only when it did not measure. */
+    readonly keyboardVisible?: boolean;
     readonly pixels?: ObservationPixels;
 } | {
     readonly kind: 'pixels';

package/dist/expect/attempt.d.ts

@@ -4,6 +4,8 @@ import type { SoftFailures } from './soft.ts';
 import type { PollScope } from './poll-scope.ts';
 export interface PublishedAttempt {
     readonly attemptId: string;
+    /** Host preparation may overlap a hosted attempt, but not a suite attempt. */
+    readonly owner: 'suite' | 'host';
     /** Setup tests owe their sessions and may not skip themselves. */
     readonly testKind: 'test' | 'setup';
     /** The config default for a poll's `timeout`. */

package/dist/mcp/catalog.js

@@ -125,7 +125,9 @@ const CONTENT_NAMED_ROLES = new Set(['status', 'alert', 'listitem']);
 /** The zero-match advice for a content-named role: match the text instead of retrying it as a name. */
 function contentNameNotFound(role, name, exact) {
     const quoted = JSON.stringify(name);
-    return `A role query matches the accessible name only, and observe shows a ${role} by its text in its place. If ${quoted} is that text, use screen.getByRole(${JSON.stringify(role)}).filter({ hasText: ${quoted} }) or screen.getByText(${quoted}).${exact ? ' Otherwise loosen the match with exact: false.' : ''}`;
+    const article = /^[aeiou]/.test(role) ? 'an' : 'a';
+    const text = `screen.getByText(${quoted}${exact ? '' : ', { exact: false }'})`;
+    return `A role query matches the accessible name only, and observe shows ${article} ${role} by its text in its place. If ${quoted} is that text, use screen.getByRole(${JSON.stringify(role)}).filter({ hasText: ${quoted} }) or ${text}.${exact ? ' Otherwise loosen the match with exact: false.' : ''}`;
 }
 /** Renders a locate result: the count, the verdict a test would get, and the nodes, each through the attempt's redactor. */
 export function describeLocate(query, count, nodes, redaction) {

package/dist/run/execute.js

@@ -28,7 +28,7 @@ import { isFailedStatus } from './records.js';
 import { traceScreen } from './step-screens.js';
 import { runWithRetries } from './retry.js';
 import { runSerialUnit } from './serial.js';
-import { interruptedSkip, pairKey, pairResult, unstartedResult } from './units.js';
+import { interruptedInPhase, interruptedSkip, pairKey, pairResult, unstartedResult } from './units.js';
 import { adoptSecrecy, carriedSecrecy, processSecrets, registerDerivedSecrets, redactForSession, resolveSecretValue, sessionSecrecy, staticSecretLedger } from './secrecy.js';
 import { isSecret } from '../secrets.js';
 import { SessionStaging, SessionStore, targetIdentity } from './sessions.js';
@@ -729,7 +729,7 @@ export class TargetExecutor {
             // `expect.poll` and `expect.soft` take no fixture, so the attempt they
             // run on is published here and cleared when `attemptEnd` fires in `finally`.
             const soft = new SoftFailures();
-            publishAttempt({ attemptId, testKind: pair.test.kind, assertionTimeout: this.config.assertionTimeout, budget, soft }, attemptEnd.signal);
+            publishAttempt({ attemptId, owner: 'suite', testKind: pair.test.kind, assertionTimeout: this.config.assertionTimeout, budget, soft }, attemptEnd.signal);
             const beforeEachHooks = this.realms.hooksFor(realm, registered, 'beforeEach');
             const afterEachHooks = this.realms.hooksFor(realm, registered, 'afterEach');
             // The test's own chain decides the fixture set; hooks get the same
@@ -802,7 +802,7 @@ export class TargetExecutor {
             // down with the worker process; the attempt records the interrupt and
             // moves to cleanup.
             const work = this.options.isolated
-                ? withAbort(runInPollScope(bodyPolls, mainWork), this.interruptSignal, () => new E2EError('interrupted', 'INTERRUPTED', `run interrupted in phase ${phase}`))
+                ? withAbort(runInPollScope(bodyPolls, mainWork), this.interruptSignal, () => new E2EError('interrupted', 'INTERRUPTED', interruptedInPhase(this.interruptSignal, phase)))
                 : runInPollScope(bodyPolls, mainWork);
             const body = Promise.race([
                 work,

package/dist/run/open-session.js

@@ -6,44 +6,60 @@ import { allocateTargetPorts } from './app-ports.js';
 import { processSecrets, registerStaticSecrets } from './secrecy.js';
 import { selectTarget } from './select-target.js';
 import { openStandaloneHost } from './standalone.js';
+import { reserveHostedRun } from './public-ownership.js';
 /** Opens the worker-scoped owner of preparation, app processes, and engine initialization. */
 export async function openHost(options = {}) {
     return redactOpening(() => openHostWorker(options));
 }
 /** Loads the selected target and opens its worker behind the redacted public boundary. */
 async function openHostWorker(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const env = options.env ?? process.env;
-    const loaded = await loadHostConfig(cwd, options.config, env);
-    registerStaticSecrets(loaded.allSecrets);
-    const { config, target } = await allocateTargetPorts(loaded, selectTarget(loaded, options.target, 'pass `target` to openHost'));
-    const host = await openStandaloneHost({
-        config, target, headed: options.headed ?? false, env,
-        signal: options.signal ?? new AbortController().signal,
-        ...(options.onNotice === undefined ? {} : { notice: options.onNotice }),
-    });
-    return {
-        runId: host.runId, target: target.name, close: host.close,
-        [Symbol.asyncDispose]: () => dispose(host.close, 'host'),
-        openSession: (sessionOptions) => redactOpening(async () => {
-            if (typeof sessionOptions.name !== 'string')
-                throw new ConfigurationError('INVALID_CONFIG', 'a hosted session requires a string name');
-            const attempt = await host.openAttempt({
-                name: sessionOptions.name,
-                signal: sessionOptions.signal ?? new AbortController().signal,
-                timeoutMs: sessionOptions.timeout ?? config.timeout,
-                agent: sessionOptions.agent,
-                ...(sessionOptions.onStep === undefined ? {} : { onProgress: sessionOptions.onStep }),
-            });
-            return {
-                runId: attempt.runId, attemptId: attempt.attemptId, target: target.name,
-                fixtures: attempt.fixtures,
-                artifactsDir: attempt.artifactsDir, tracePath: attempt.tracePath,
-                steps: () => attempt.steps.all(), close: attempt.close,
-                [Symbol.asyncDispose]: () => dispose(attempt.close, 'session'),
-            };
-        }),
-    };
+    const release = reserveHostedRun();
+    try {
+        const cwd = options.cwd ?? process.cwd();
+        const env = options.env ?? process.env;
+        const loaded = await loadHostConfig(cwd, options.config, env);
+        registerStaticSecrets(loaded.allSecrets);
+        const { config, target } = await allocateTargetPorts(loaded, selectTarget(loaded, options.target, 'pass `target` to openHost'));
+        const host = await openStandaloneHost({
+            config, target, headed: options.headed ?? false, env,
+            signal: options.signal ?? new AbortController().signal,
+            ...(options.onNotice === undefined ? {} : { notice: options.onNotice }),
+        });
+        const close = async () => {
+            try {
+                return await host.close();
+            }
+            finally {
+                release();
+            }
+        };
+        return {
+            runId: host.runId, target: target.name, close,
+            [Symbol.asyncDispose]: () => dispose(close, 'host'),
+            openSession: (sessionOptions) => redactOpening(async () => {
+                if (typeof sessionOptions.name !== 'string')
+                    throw new ConfigurationError('INVALID_CONFIG', 'a hosted session requires a string name');
+                const attempt = await host.openAttempt({
+                    name: sessionOptions.name,
+                    signal: sessionOptions.signal ?? new AbortController().signal,
+                    timeoutMs: sessionOptions.timeout ?? config.timeout,
+                    agent: sessionOptions.agent,
+                    ...(sessionOptions.onStep === undefined ? {} : { onProgress: sessionOptions.onStep }),
+                });
+                return {
+                    runId: attempt.runId, attemptId: attempt.attemptId, target: target.name,
+                    fixtures: attempt.fixtures,
+                    artifactsDir: attempt.artifactsDir, tracePath: attempt.tracePath,
+                    steps: () => attempt.steps.all(), close: attempt.close,
+                    [Symbol.asyncDispose]: () => dispose(attempt.close, 'session'),
+                };
+            }),
+        };
+    }
+    catch (cause) {
+        release();
+        throw cause;
+    }
 }
 /** Opening errors go straight to the external runner, never through a report writer. */
 async function redactOpening(open) {

package/dist/run/process-output.d.ts

@@ -11,6 +11,10 @@ import type { ListReporterOutput } from '../report/list.ts';
 export type OutputStream = 'stdout' | 'stderr';
 /** Writes text to one stream of the terminal; the callback fires once the stream took it. Answers false while the stream is backed up, like `Writable.write`. */
 export type TerminalWrite = (text: string, callback?: () => void) => boolean;
+/** The CLI owns every process write, including timers that print after a run ends. */
+export declare function claimProcessOutput(ledger: SecretLedger): RunnerOutput;
+/** Embedded runs own their async output; caller output resumes once cleanup ends. */
+export declare function withProcessOutput<T>(ledger: SecretLedger, run: (output: RunnerOutput) => Promise<T>): Promise<T>;
 /** Where runner output goes instead of the terminal while the list reporter shows the run. */
 export interface OutputView {
     /** Prints redacted text from `stream`. */

package/dist/run/process-output.js

@@ -7,6 +7,65 @@
  * what is printed meanwhile is held, and withheld if the load fails.
  */
 import { StreamRedactor } from '../internal/redact.js';
+import { AsyncLocalStorage, AsyncResource } from 'node:async_hooks';
+import { realmSlot } from '../internal/realm-slot.js';
+const BYTE_ENCODINGS = new Set(['hex', 'base64', 'base64url']);
+const routingSlot = realmSlot('e2e.process-output.routing.v1');
+/** One process dispatcher preserves redaction for asynchronous work that outlives a suite. */
+function routing() {
+    const streams = { stdout: process.stdout, stderr: process.stderr };
+    let state = routingSlot.get(process);
+    if (state === undefined) {
+        state = {
+            scope: new AsyncLocalStorage(),
+            terminal: {
+                stdout: streams.stdout.write.bind(streams.stdout),
+                stderr: streams.stderr.write.bind(streams.stderr),
+            },
+            dispatchers: {},
+            process: undefined,
+        };
+        routingSlot.set(process, state);
+    }
+    for (const name of ['stdout', 'stderr']) {
+        if (streams[name].write === state.dispatchers[name])
+            continue;
+        const forward = streams[name].write.bind(streams[name]);
+        state.terminal[name] = (text, callback) => {
+            const done = callback === undefined ? undefined : AsyncResource.bind(callback);
+            return state.scope.run(null, () => forward(text, done));
+        };
+        const dispatch = ((chunk, encoding, callback) => {
+            const context = state.scope.getStore();
+            const output = context === null ? undefined : context ?? state.process;
+            if (output === undefined)
+                return forward(chunk, encoding, callback);
+            const done = typeof encoding === 'function' ? encoding : callback;
+            const bytes = typeof chunk === 'string' && typeof encoding === 'string' && BYTE_ENCODINGS.has(encoding);
+            return output.write(name, bytes ? Buffer.from(chunk, encoding) : chunk, done);
+        });
+        state.dispatchers[name] = dispatch;
+        streams[name].write = dispatch;
+    }
+    return state;
+}
+/** The CLI owns every process write, including timers that print after a run ends. */
+export function claimProcessOutput(ledger) {
+    const state = routing();
+    state.process ??= new RunnerOutput(state.terminal, ledger);
+    return state.process;
+}
+/** Embedded runs own their async output; caller output resumes once cleanup ends. */
+export async function withProcessOutput(ledger, run) {
+    const state = routing();
+    const output = new RunnerOutput(state.terminal, ledger);
+    try {
+        return await state.scope.run(output, () => run(output));
+    }
+    finally {
+        output.end();
+    }
+}
 /** The warning that stands in for what a config printed before it failed to load. */
 function withheldWarning(bytes) {
     return `withheld ${bytes} bytes of output printed while the config failed to load: its secrets are unknown, so the output cannot be redacted`;

package/dist/run/public-ownership.d.ts

@@ -0,0 +1,4 @@
+/** Reserves the process before a suite can change registries or claim output. */
+export declare function reserveSuiteRun(): () => void;
+/** Holds a host's process ownership from before config loading through close. */
+export declare function reserveHostedRun(): () => void;

package/dist/run/public-ownership.js

@@ -0,0 +1,38 @@
+import { currentAttempt } from '../expect/attempt.js';
+import { ConfigurationError } from '../internal/errors.js';
+import { realmSlot } from '../internal/realm-slot.js';
+const slot = realmSlot('e2e.public-runner.owners.v1');
+/** Public runner copies in isolated realms share one set of process owners. */
+function owners() {
+    let state = slot.get(globalThis);
+    if (state === undefined) {
+        state = { suite: undefined, hosts: new Set() };
+        slot.set(globalThis, state);
+    }
+    return state;
+}
+/** Reserves the process before a suite can change registries or claim output. */
+export function reserveSuiteRun() {
+    const state = owners();
+    if (state.suite !== undefined)
+        throw new ConfigurationError('RUNNER_BUSY', 'a public run is already in progress; await it before starting another');
+    if (state.hosts.size > 0)
+        throw new ConfigurationError('RUNNER_BUSY', 'a hosted runner is still open; close it before starting a suite');
+    if (currentAttempt() !== undefined)
+        throw new ConfigurationError('RUNNER_BUSY', 'an attempt is still running; close it before starting a suite');
+    const owner = {};
+    state.suite = owner;
+    return () => { if (state.suite === owner)
+        state.suite = undefined; };
+}
+/** Holds a host's process ownership from before config loading through close. */
+export function reserveHostedRun() {
+    const state = owners();
+    if (state.suite !== undefined)
+        throw new ConfigurationError('RUNNER_BUSY', 'a suite is running; await it before opening a host');
+    if (currentAttempt()?.owner === 'suite')
+        throw new ConfigurationError('RUNNER_BUSY', 'a suite attempt is still running; await it before opening a host');
+    const owner = {};
+    state.hosts.add(owner);
+    return () => { state.hosts.delete(owner); };
+}

package/dist/run/public-run.d.ts

@@ -0,0 +1,15 @@
+import type { Report } from '../types.ts';
+import type { RunExitCode, RunStatus } from './events.ts';
+import { type ListOptions, type RunOptions as InternalRunOptions } from './runner.ts';
+/** Options for executing a suite through the public runner API. */
+export type SuiteRunOptions = Pick<ListOptions, 'cwd' | 'config' | 'files'> & Pick<InternalRunOptions, 'interruptSignal' | 'onEvent'>;
+/** The completed run's report and output paths, without live engine or configuration handles. */
+export interface RunResult {
+    readonly exitCode: RunExitCode;
+    readonly status: RunStatus;
+    readonly report: Report;
+    readonly reportPath: string | undefined;
+    readonly aiTracePath: string | undefined;
+}
+/** Executes a suite without exiting the caller; await its cleanup before starting another run. */
+export declare function runSuite(options?: SuiteRunOptions): Promise<RunResult>;

package/dist/run/public-run.js

@@ -0,0 +1,58 @@
+import { AsyncResource } from 'node:async_hooks';
+import path from 'node:path';
+import { packageVersion } from '../internal/package-version.js';
+import { runsFromCheckout } from '../telemetry/checkout.js';
+import { runCompletedEvent } from '../telemetry/events.js';
+import { Telemetry } from '../telemetry/telemetry.js';
+import { withProcessOutput } from './process-output.js';
+import { reserveSuiteRun } from './public-ownership.js';
+import { processSecrets } from './secrecy.js';
+import { run as execute, toSelectionRunOptions } from './runner.js';
+/** Executes a suite without exiting the caller; await its cleanup before starting another run. */
+export async function runSuite(options = {}) {
+    const release = reserveSuiteRun();
+    try {
+        const telemetry = new Telemetry({
+            version: packageVersion(import.meta.url, '../../package.json', '0.0.0'),
+            checkout: runsFromCheckout(import.meta.url),
+            cwd: path.resolve(options.cwd ?? process.cwd()),
+        });
+        telemetry.notice();
+        const onEvent = options.onEvent === undefined ? undefined : AsyncResource.bind(options.onEvent);
+        const outcome = await withProcessOutput(processSecrets, async (output) => {
+            const interrupt = ownedInterrupt(options.interruptSignal);
+            try {
+                return await execute({
+                    ...toSelectionRunOptions({ cwd: options.cwd, config: options.config, files: options.files }),
+                    quiet: true,
+                    processOutput: output,
+                    interruptSignal: interrupt.signal,
+                    onEvent,
+                });
+            }
+            finally {
+                interrupt.dispose();
+            }
+        });
+        telemetry.record(runCompletedEvent(outcome.report, { command: 'runner.run', flags: [], config: outcome.config }));
+        // The caller's result never waits on the network; the send has its own deadline.
+        void telemetry.flush();
+        const { exitCode, status, report, reportPath, aiTracePath } = outcome;
+        return { exitCode, status, report, reportPath, aiTracePath };
+    }
+    finally {
+        release();
+    }
+}
+/** Caller cancellation enters the suite's async context before invoking its listeners. */
+function ownedInterrupt(signal) {
+    if (signal === undefined)
+        return { signal: undefined, dispose: () => undefined };
+    const controller = new AbortController();
+    const abort = AsyncResource.bind(() => controller.abort(signal.reason));
+    if (signal.aborted)
+        abort();
+    else
+        signal.addEventListener('abort', abort, { once: true });
+    return { signal: controller.signal, dispose: () => signal.removeEventListener('abort', abort) };
+}

package/dist/run/runner.d.ts

@@ -250,3 +250,12 @@ export interface RunOutcome {
 }
 /** Executes one complete run and returns the outcome without exiting. */
 export declare function run(options?: RunOptions): Promise<RunOutcome>;
+/**
+ * What `loadRunConfig`, `selectionInputs`, and `validateRunOptions` read.
+ * `run` passes `RunOptions`; `list` translates the public bag into these
+ * (`config` string to `configPath`, object to `rawConfig`, `targets` to `targetIds`).
+ */
+type SelectionRunOptions = Pick<RunOptions, 'configPath' | 'rawConfig' | 'files' | 'tags' | 'tagMode' | 'excludeTags' | 'grep' | 'grepInvert' | 'lastFailed' | 'freshGraph' | 'shard' | 'targetIds' | 'passWithNoTests' | 'output' | 'maxFailures' | 'maxDuration' | 'repeatEach'>;
+/** The public `list` bag as the options config loading and selection already take. */
+export declare function toSelectionRunOptions(options: ListOptions): SelectionRunOptions;
+export {};

package/dist/run/runner.js

@@ -731,7 +731,7 @@ function workerEnvFor(plans, env) {
     };
 }
 /** The public `list` bag as the options config loading and selection already take. */
-function toSelectionRunOptions(options) {
+export function toSelectionRunOptions(options) {
     const { config, targets, ...rest } = options;
     return {
         ...rest,

package/dist/run/standalone-attempt.js

@@ -36,7 +36,7 @@ export function reserveAttempt(worker, options) {
         return { attemptId, options, end, signal, budget, soft, polls, release: () => undefined };
     const { config } = worker;
     const publication = new AbortController();
-    publishAttempt({ attemptId, testKind: 'test', assertionTimeout: config.assertionTimeout, budget, soft, polls }, publication.signal);
+    publishAttempt({ attemptId, owner: 'host', testKind: 'test', assertionTimeout: config.assertionTimeout, budget, soft, polls }, publication.signal);
     // The live attempt's secrets resolve against its own config while other hosts hold theirs.
     const releaseRegistry = holdSecretRegistry(config, { live: true });
     return { attemptId, options, end, signal, budget, soft, polls, release: () => { publication.abort(); releaseRegistry(); } };
@@ -102,16 +102,23 @@ export async function launchAttempt(worker, reservation, onClosed) {
         await closeOpened({ status: 'failed', cleanup: 'complete' });
         throw cause;
     }
+    const { deadline } = budget;
+    let timedOut = false;
+    /** Fails the attempt as timed out, once, and cuts whatever is still in flight. */
+    const expire = () => {
+        if (timedOut)
+            return;
+        timedOut = true;
+        const timeout = new TestTimeoutError(`session timed out after ${options.timeoutMs} ms`);
+        recordFailure(timeout, 'body');
+        end.abort(timeout);
+    };
     // An engine that ignores its operation's timeout, or a model call, must not
     // outlive the deadline: the attempt is cut the way a run's body is. One
     // tick after it, so an operation that honors the deadline reports its own
     // failure first; whatever is still in flight then fails as timed out.
-    const remaining = budget.deadline.remaining() + 1;
-    const expiry = remaining > MAX_TIMER_MS ? undefined : setTimeout(() => {
-        const timedOut = new TestTimeoutError(`session timed out after ${options.timeoutMs} ms`);
-        recordFailure(timedOut, 'body');
-        end.abort(timedOut);
-    }, remaining);
+    const remaining = deadline.remaining() + 1;
+    const expiry = remaining > MAX_TIMER_MS ? undefined : setTimeout(expire, remaining);
     expiry?.unref();
     const startedAt = timestamp();
     const startedMs = Date.now();
@@ -120,6 +127,9 @@ export async function launchAttempt(worker, reservation, onClosed) {
     const close = () => {
         ending ??= (async () => {
             clearTimeout(expiry);
+            // The deadline decides the outcome, not whether the timer ran before close.
+            if (deadline.expired())
+                expire();
             const abandonedPoll = polls.close();
             const abandonedStep = steps.abandonRunning();
             end.abort();

package/dist/run/units.d.ts

@@ -66,6 +66,11 @@ export declare function timeLimitSkip(limit: TimeLimit): SkipInfo;
  * so), else the plain interrupt.
  */
 export declare function interruptedSkip(signal: AbortSignal, fallback?: SkipInfo): SkipInfo;
+/**
+ * The message of an attempt an interrupt cut short in `phase`, naming the
+ * limit that stopped the run when the interrupt carried one.
+ */
+export declare function interruptedInPhase(signal: AbortSignal, phase: string): string;
 /**
  * Builds a result for one pair, narrowing the collected test to its identity
  * so no test function or realm state can reach a record or the wire.

package/dist/run/units.js

@@ -106,6 +106,15 @@ export function interruptedSkip(signal, fallback = INTERRUPTED_BEFORE_START) {
     const reason = signal.reason;
     return isSkipInfo(reason) ? reason : fallback;
 }
+/**
+ * The message of an attempt an interrupt cut short in `phase`, naming the
+ * limit that stopped the run when the interrupt carried one.
+ */
+export function interruptedInPhase(signal, phase) {
+    const reason = signal.reason;
+    const message = `run interrupted in phase ${phase}`;
+    return isSkipInfo(reason) ? `${message}: ${reason.reason}` : message;
+}
 function isSkipInfo(value) {
     return typeof value === 'object' && value !== null && typeof value.cause === 'string' && typeof value.reason === 'string';
 }

package/dist/runner.d.ts

@@ -1,14 +1,7 @@
-/**
- * In-process runner APIs. `list` collects and selects as `e2e list` does and
- * stops before any app, engine, or worker starts. `openHost` opens a reusable
- * worker whose per-test sessions share the runner's attempt lifecycle.
- * Importing `e2e` does not load this module.
- *
- * `ConfigurationError` is also on `e2e/engine`. A caller of `list` or
- * `openHost` matches `error.code` from here, without importing the engine
- * contract.
- */
+/** Runner APIs live on e2e/runner so importing e2e does not load them; ConfigurationError is shared with e2e/engine. */
 export { ConfigurationError, isE2EError, type SerializedError } from './internal/errors.ts';
 export { list, type ListOptions, type ListResult, type ListedPair } from './run/runner.ts';
+export { runSuite as run, type SuiteRunOptions as RunOptions, type RunResult } from './run/public-run.ts';
+export type { RunEventSink } from './run/events.ts';
 export { openHost, type E2EHost, type E2ESession, type OpenHostOptions, type OpenSessionOptions } from './run/open-session.ts';
 export type { StepProgress, StepRecord } from './run/steps.ts';

package/dist/runner.js

@@ -1,13 +1,5 @@
-/**
- * In-process runner APIs. `list` collects and selects as `e2e list` does and
- * stops before any app, engine, or worker starts. `openHost` opens a reusable
- * worker whose per-test sessions share the runner's attempt lifecycle.
- * Importing `e2e` does not load this module.
- *
- * `ConfigurationError` is also on `e2e/engine`. A caller of `list` or
- * `openHost` matches `error.code` from here, without importing the engine
- * contract.
- */
+/** Runner APIs live on e2e/runner so importing e2e does not load them; ConfigurationError is shared with e2e/engine. */
 export { ConfigurationError, isE2EError } from './internal/errors.js';
 export { list } from './run/runner.js';
+export { runSuite as run } from './run/public-run.js';
 export { openHost } from './run/open-session.js';

package/dist/telemetry/telemetry.d.ts

@@ -6,8 +6,8 @@
  * command never waits on telemetry for more than the flush budget and never
  * fails because of it. A long-lived command (`e2e mcp`) sends what it has
  * queued as it goes with `sendQueued`, so a client that kills it loses only
- * what was still in progress. Telemetry is a CLI concern only: the runner
- * never constructs this class.
+ * what was still in progress. Besides the CLI, only the public `run()` on
+ * `e2e/runner` constructs this class, one per call.
  *
  * Off means off at every step. `E2E_TELEMETRY_DISABLED`, `DO_NOT_TRACK`, a
  * source checkout of the repository, an `e2e telemetry disable`, or a

package/dist/telemetry/telemetry.js

@@ -6,8 +6,8 @@
  * command never waits on telemetry for more than the flush budget and never
  * fails because of it. A long-lived command (`e2e mcp`) sends what it has
  * queued as it goes with `sendQueued`, so a client that kills it loses only
- * what was still in progress. Telemetry is a CLI concern only: the runner
- * never constructs this class.
+ * what was still in progress. Besides the CLI, only the public `run()` on
+ * `e2e/runner` constructs this class, one per call.
  *
  * Off means off at every step. `E2E_TELEMETRY_DISABLED`, `DO_NOT_TRACK`, a
  * source checkout of the repository, an `e2e telemetry disable`, or a

package/docs/browser.mdx

@@ -78,13 +78,18 @@ A function handler gets the dialog and must call `accept(text?)` or
 ## Download a file
 
 ```ts
+import { readFile } from 'node:fs/promises';
+
 const file = await browser.waitForDownload(() =>
   screen.getByRole('link', 'Export CSV').tap(),
 );
+const csv = await readFile(file.absolutePath, 'utf8');
+expect(csv).toContain('Invoice');
 ```
 
-e2e saves the file as a `download` artifact. `file.path` is relative to the
-attempt's artifact directory, not to the project.
+e2e saves the file as a `download` artifact. Read it through
+`file.absolutePath`, which works with hosted browsers too. `file.path` is
+relative to the attempt's artifact directory, not to the project.
 
 ## Reach into an iframe
 

package/docs/decision-models.mdx

@@ -109,10 +109,15 @@ newest screen: `tap`, `type`, `typeSecret`, `submit`, `select`, `check`,
 `upload`, `hover`, `secondary_tap` (a right-click), `double_tap`,
 `long_press`, `drag`, `scroll_to`, `scroll_up`, `scroll_down`, and `back`.
 Hover, right-click, drag, and scroll-to also reach labeled nodes that are
-not controls, such as a card that opens a menu on hover. While an on-screen
+not controls, such as a card that opens a menu on hover, and a drag can drop
+onto any of them. `tap` also reaches text fields, to open a date picker or a
+suggestion list. While an on-screen
 keyboard shows on an engine that can dismiss it, such as the mobile engine,
-the executor also offers `dismiss_keyboard`.
+the executor also offers `dismiss_keyboard`, even when the keyboard is
+missing from the tree.
 
+Every operation that acts on an element asks for its target, even when only
+one element fits it.
 Every target question has a `none` option, so a provider with no fitting
 target answers `none` instead of refusing. `none` blocks the step.
 
@@ -130,7 +135,7 @@ secret, from its declared handle.
 
 The text model also answers `waitFor` and `extract`. Instead of
 `textModel`, you can set `model` on the agents entry. With neither, the
-executor never offers `type`, `upload`, or `tap_at`.
+executor never offers `type`, `upload`, `tap_at`, or `type_at`.
 
 ## Finishing a step
 
@@ -167,17 +172,37 @@ doesn't show. The operation and target questions read the tree only.
 `agent.assert(..., { vision: true })` and `vision: 'only'` work too. After a
 secret fill in the attempt, the executor gets no pixels.
 
-The model must accept images and answer `score` questions, as
-`openai.decisionModel('gpt-6-luna')` does. A text-only model such as Jev
-refuses the screenshot. Vercel AI Gateway rejects it too, so keep `vision`
-off there.
+The model must accept images and answer `score` questions. TypeSafe Jev
+does with `@ai-sdk/typesafe-ai` 3.0.19 or later and a TypeSafe API key in
+`TYPESAFE_AI_API_KEY`:
+
+```ts title="e2e.config.ts"
+import { typeSafeAi } from '@ai-sdk/typesafe-ai';
+import { openrouter } from '@openrouter/ai-sdk-provider';
+
+const executor = decisionExecutor({
+  model: typeSafeAi.decisionModel('jev-latest'),
+  textModel: openrouter('inception/mercury-2.5'),
+  vision: true,
+});
+```
+
+`openai.decisionModel('gpt-6-luna')` takes images too. Vercel AI Gateway
+rejects the screenshot for every decision model, so keep `vision` off
+there.
 
 With a text model, vision also offers `tap_at` for a control the tree
 doesn't list. The text model names the control, such as "the 3 key on the
-keypad", and the decision model finds it on the screenshot, then on a
-zoomed crop. A point tap costs three decide calls and one text call, or one
+keypad", and the decision model finds it on the screenshot, then on two
+zoomed crops. A point tap costs four decide calls and one text call, or one
 of each to repeat a tap on the same page.
 
+When the engine can type into whatever has focus, vision also offers
+`type_at` for a drawn field. The text model names the field and the value
+from the goal, the decision model finds the field on the screenshot, and
+the executor taps it and types the value at the caret, after any text
+already there. It costs two decide calls and one text call.
+
 ## Provider options
 
 The executor's `providerOptions` go with every decide call, completion
@@ -221,8 +246,8 @@ executor takes that choice with probability 1 and confidence 0, so a
 
 - No `navigate`. In-app navigation is a `tap` on a link. URLs belong in
   test code (`browser.goto`, `app.open`).
-- No multi-select `listbox`, no `scrollUntil`, and no typing at a point
-  (`type_at`).
+- No multi-select `listbox` and no `scrollUntil`. `type_at` never clears a
+  drawn field first, so it suits empty fields.
 - The text model that names a drawn control doesn't see pixels. It can't
   follow an instruction that exists only as drawn text, such as a wizard
   that paints "tap the circle".

package/docs/executors.mdx

@@ -144,6 +144,9 @@ without acting. Engines with a keyboard add `typeText`, `pressKey`, and
 path outside the project root or a hidden one with `POLICY_DENIED`, and a
 missing file with `INVALID_ARGUMENT`.
 
+The observation's `keyboardVisible` says whether an on-screen keyboard is
+showing, and is absent when the engine can't tell.
+
 When semantic capture fails, the observation sets `treeUnavailable: true`,
 has no `tree`, and includes a screenshot if policy allows. Earlier node ids
 are invalid, and a missing tree doesn't prove a control is absent.

package/docs/migrate/playwright.mdx

@@ -187,7 +187,8 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on
 | `innerHTML()`, `dispatchEvent()`, `selectText()`, `blur()`, `highlight()` | not yet; `browser.evaluate` | missing |
 | `ariaSnapshot()` | not yet | missing |
 | `page.keyboard.press`, `keyboard.type` | `browser.keyboard.press`, `browser.keyboard.type`; plain text only, never a `Secret` | web only |
-| `keyboard.down`, `keyboard.up`, `keyboard.insertText` | not yet | missing |
+| `keyboard.down`, `keyboard.up` | `browser.keyboard.down`, `browser.keyboard.up`; keys and modifiers stay held until released | web only |
+| `keyboard.insertText` | not yet | missing |
 | `page.mouse.click(x, y)` | `screen.tapAt({ x, y })`, viewport coordinates | renamed |
 | `mouse.move`, `down`, `up` as a drag | `screen.swipe({ from, to })` | renamed |
 | `page.dragAndDrop(source, target, { sourcePosition, targetPosition })` | `source.dragTo(target)`, which takes no positions; for `sourcePosition` or `targetPosition`, `screen.swipe({ from, to })` with each `boundingBox()` origin plus its offset | renamed |

package/docs/reference/engine.mdx

@@ -629,6 +629,12 @@ export interface EngineSnapshot {
    * read whole.
    */
   readonly truncated?: boolean;
+  /**
+   * Whether an on-screen keyboard is showing, as the engine measured it apart
+   * from `root`. Set `false` when it measured none, and omit it only when the
+   * engine did not measure it.
+   */
+  readonly keyboardVisible?: boolean;
   /** Semantic capture failed; only fresh, independently masked pixels are evidence. */
   readonly treeUnavailable?: true;
   /** Masked pixels, when requested and producible; omitted otherwise. */

package/docs/reference/errors.mdx

@@ -104,6 +104,7 @@ These appear in terminal output and in the report as plain string codes.
 | `UNSUPPORTED_ARTIFACT` | A [`video` mode](/reference/config#recording) set on a target, or on a test that will run there, records on some attempt, and the target's engine cannot record video. The message names the target and, for a test's mode, the test. A mode from the config root or `--video` never raises it: it applies to the targets that can record, with a notice naming the rest | configuration | 2 |
 | `UNSUPPORTED_CAPABILITY` | A fixture, action, or tier the target's engine does not declare: a contributed fixture it does not contribute, `screen` without `locate`, state restore without `state`, screenshots without `artifacts`, `app.clearState()` on a persistent browser context (the message names the mode), or `agent.assert` `vision` with an executor that does not declare `vision: true` | configuration | 2 |
 | `NO_TESTS` | Zero runnable ordinary test-target pairs. The message names the cause: no file matched the `tests` globs (with look-alike files), a positional matched nothing (naming the `!` entry that excludes a file it names), a file registered no tests, or filters excluded everything. Suppress with `--pass-with-no-tests`. | configuration | 2 |
+| `RUNNER_BUSY` | A suite overlapped another suite, an opening or open host, or a live attempt; or a host opened during a suite. Await the suite and close existing hosts before retrying. | configuration | 2 |
 | `NO_LAST_RUN` | `--last-failed` found no `report.json` where the run writes it, or a file there that is not a `report-1` document. Run once without the flag first. | configuration | 2 |
 | `ONLY_IN_CI` | A focused test reached a CI run | configuration | 2 |
 | `COLLECTION_ERROR` | Registration outside collection, an invalid title, a non-function body, an async `describe` body, nested serial groups, an option forbidden inside a serial group, a setup test inside `describe`, an invalid session name, a malformed test option such as `tags` that is not a list of distinct names, a test or `describe` option key the call does not take (the message names the nearest one), a test file that fails to import (in a run with no positionals, or a file the positionals selected), a session that a selected test consumes or `e2e explore --session` names but no collected setup test produces (the message lists the declared sessions), a consumed session on a target whose engine has no `state` capability to save it, or a positional path outside the project root | configuration | 2 |
@@ -132,7 +133,7 @@ These appear in terminal output and in the report as plain string codes.
 | `SESSION_KEY_INVALID` | A worker received a session key that is not 32 bytes. Packaging or IPC fault. | infrastructure | 3 |
 | `REPORT_WRITE_FAILED` | `report.json` or `ai-trace.json` could not be written. Recorded as a run error; the in-memory outcome is still complete. A `junit.xml` that could not be written is the `junit` reporter's stderr line instead | infrastructure | 3 |
 | `EVALUATE_FAILED` | `browser.evaluate` threw inside the page (`@e2e-dev/web`) | test | 1 |
-| `INTERRUPTED` | A user or CI signal aborted the run | interrupted | 130 |
+| `INTERRUPTED` | A user or CI signal aborted the run. A test cut short by `--max-failures` or the time limit also ends with this code, its message naming the limit; that run exits 1, not 130 | interrupted | 130 |
 
 Errors raised by argument validation in test code use `INVALID_ARGUMENT` and
 `INVALID_LOCATOR`, both test failures with exit code 1. An unclassified thrown

package/docs/reference/runner.mdx

@@ -1,12 +1,69 @@
 ---
 title: "e2e/runner"
-description: "List the tests a selection would run, or host e2e sessions in another test runner."
+description: "Run a test suite, list its selection, or host e2e sessions in another test runner."
 icon: "file-lines"
-"og:image": "https://e2e.tester.army/docs/images/og/reference/runner.png?v=a4c80234f3"
-"twitter:image": "https://e2e.tester.army/docs/images/og/reference/runner.png?v=a4c80234f3"
+"og:image": "https://e2e.tester.army/docs/images/og/reference/runner.png?v=98c298d3ed"
+"twitter:image": "https://e2e.tester.army/docs/images/og/reference/runner.png?v=98c298d3ed"
 ---
 
-`e2e/runner` runs e2e in process without `e2e run`. `list` returns a selection. `openHost` prepares a target for your test runner, and `host.openSession` opens a fresh attempt for each test. Importing `e2e` from a test file does not load the runner.
+`e2e/runner` runs a suite from code without invoking the CLI. `run` executes tests and returns their report; `list` returns a selection. `openHost` prepares a target for your test runner, and `host.openSession` opens a fresh attempt for each test. Importing `e2e` from a test file does not load the runner.
+
+## run
+
+`run(options?: RunOptions)` executes a complete suite and returns `Promise<RunResult>`. It finishes cleanup before resolving and never exits the caller's process.
+
+```ts
+import type { E2EConfig } from 'e2e';
+import { run } from 'e2e/runner';
+import { web } from '@e2e-dev/web';
+
+const config: E2EConfig = {
+  targets: [{ name: 'web', engine: web(), app: { url: 'http://localhost:3000' } }],
+};
+const controller = new AbortController();
+const result = await run({
+  config,
+  files: ['tests/signup.e2e.ts'],
+  interruptSignal: controller.signal,
+  onEvent(event) {
+    if (event.type === 'test-started') console.log(event.title);
+  },
+});
+
+console.log(result.status, result.report.run.summary);
+```
+
+### Execution options
+
+`run` accepts these options. Put execution settings, such as retries and workers, in the config.
+
+| Option | Meaning |
+| --- | --- |
+| `cwd` | Project directory. Defaults to the current working directory. |
+| `config` | Config file path or an `E2EConfig` value. Omit it to discover `e2e.config.ts`. |
+| `files` | File selection: paths, globs, bare names, or `file:line`. Omit it to run the configured suite. |
+| `interruptSignal` | Abort to interrupt tests and execute teardown. |
+| `onEvent` | Receives typed progress events. Must not block; a throwing or rejecting callback is disabled without failing the run. |
+
+Runtime config runs with one worker in the caller's process. A file config supports the configured worker processes. Terminal progress is disabled; use `onEvent` for progress.
+
+Helper modules your test files import stay cached between `run` calls in the same process, so edits to them need a new process.
+
+### Completed result
+
+| Field | Meaning |
+| --- | --- |
+| `exitCode` | The CLI-equivalent exit code: `0`, `1`, `2`, `3`, `4`, or `130`. |
+| `status` | `passed`, `failed`, `blocked`, `error`, or `interrupted`. |
+| `report` | The complete report. Read `report.run.results`, `report.run.errors`, and `report.run.summary` for outcomes. |
+| `reportPath` | Absolute path to `report.json`, or `undefined` if it could not be written. |
+| `aiTracePath` | AI trace path, or `undefined` when no AI trace was written. |
+
+Test failures, config failures, and interruption resolve with their status and errors in the report. Overlapping suites reject with `RUNNER_BUSY`. Close every host before running a suite, and await the suite before opening a host.
+
+Each run that returns a report sends one anonymous [`e2e_run_completed`](/telemetry) event, with the same opt-outs as the CLI. The first call can print the telemetry notice on stderr.
+
+Suite output uses UTF-8 text redaction and does not preserve binary data. Your application's logs and progress callback output stay under your control.
 
 ## list
 

package/docs/reference/web.mdx

@@ -341,6 +341,10 @@ export interface Browser extends Expectable<BrowserExpectation> {
   readonly keyboard: {
     /** Sends one key. */
     press(key: string): Promise<void>;
+    /** Holds a key or modifier until up, with repeat on another down. */
+    down(key: string): Promise<void>;
+    /** Releases a held key. */
+    up(key: string): Promise<void>;
     /** Types plain text. */
     type(text: string): Promise<void>;
   };
@@ -632,9 +636,9 @@ page it opens. Each defaults to the browser's own.
 every open tab and every tab opened after them, through `app.restart()` and
 `app.clearState()`. It works before the first navigation, so the next
 `app.open` loads with them. A feature it leaves out keeps its value. A tab
-the app opens itself paints with the configured values and gets a test's
-change as it appears, on a persistent context too. A
-feature or value outside `WebMedia` is `INVALID_CONFIG` in `web()` and
+the app opens itself gets a test's change as it appears, on a persistent
+context too, so a script it runs at load may still read the configured
+values. A feature or value outside `WebMedia` is `INVALID_CONFIG` in `web()` and
 `INVALID_ARGUMENT` in `emulateMedia`.
 
 ```ts

package/docs/telemetry.mdx

@@ -67,7 +67,9 @@ sends nothing.
 Each command sends one `e2e_cli_session` event. `run` and `explore` also
 send `e2e_run_completed`, `init` sends `e2e_init_completed`, and `mcp` sends
 one `e2e_mcp_session` per MCP session. `--help` and `--version` send
-nothing, also on a command.
+nothing, also on a command. `run()` from `e2e/runner` sends one
+`e2e_run_completed` per run that returns a report, and no session event. Its
+first call can print the notice below on stderr.
 
 The events go in one request when the command ends, with a two-second
 deadline. `e2e mcp` sends each MCP session event in its own request. Events
@@ -112,11 +114,11 @@ hold only the properties below.
 | `skill`, `mcp`, `install` | Whether the agent skill, the MCP registration, and the dependency install were chosen |
 
 </Accordion>
-<Accordion title="e2e_run_completed, once per e2e run or e2e explore">
+<Accordion title="e2e_run_completed, once per e2e run, e2e explore, or completed run()">
 
 | Property | Value |
 | --- | --- |
-| `command` | `run` or `explore` |
+| `command` | `run`, `explore`, or `runner.run` for `run()` from `e2e/runner` |
 | `status`, `exit_code`, `duration_ms` | The run's outcome |
 | `flags` | The names of the flags given to the run command, never their values |
 | `tests_discovered`, `tests_selected`, `tests_executed`, `tests_passed`, `tests_failed`, `tests_interrupted`, `tests_flaky`, `tests_skipped` | The summary counts |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "e2e",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "SDK, runner, and CLI for agentic end-to-end testing",
   "keywords": [
     "e2e",
@@ -132,7 +132,7 @@
     "@ai-sdk/openai": "4.0.90",
     "@ai-sdk/openai-compatible": "3.0.53",
     "@ai-sdk/xai": "5.0.4",
-    "@e2e-dev/web": "0.15.0",
+    "@e2e-dev/web": "0.15.1",
     "@modelcontextprotocol/client": "2.2.0",
     "@openrouter/ai-sdk-provider": "3.1.0",
     "@types/node": "26.6.2",

package/skills/e2e/references/bug-bash.md

@@ -80,7 +80,10 @@ const persona = { model: gateway('openai/gpt-6-luna-fast'), maxSteps: 40, maxMod
 export default {
   ...shared,
   // The project's tests, so a repro can use its setup tests' sessions, plus the repro tests from step 6.
-  tests: [shared.tests ?? 'tests/**/*.e2e.ts', 'tests/bugbash/**/*.e2e.ts'].flat(),
+  tests: [
+    ...[shared.tests ?? 'tests/**/*.e2e.ts'].flat().filter((glob) => !glob.startsWith('!tests/bugbash/')),
+    'tests/bugbash/**/*.e2e.ts',
+  ],
   // The app already runs: no command.
   targets: [{ name: 'web', engine: web(), app: { url: 'http://127.0.0.1:3000' } }],
   retries: 0,

package/skills/e2e/references/running.md

@@ -79,6 +79,13 @@ target names.
 npx e2e list tests/signup.e2e.ts --tag smoke --reporter json
 ```
 
+`import { run } from 'e2e/runner'` executes the suite and returns its report
+without exiting the caller. Pass `cwd`, `config`, and `files` to select the
+project and tests; `onEvent` receives progress and `interruptSignal` cancels
+with teardown. A runtime config uses one in-process worker. Await each run
+before starting the next and close every host first; overlaps reject with
+`RUNNER_BUSY`.
+
 With a `package.json` script `"test:e2e": "e2e run"`, pnpm forwards `--`
 literally: `pnpm test:e2e -- --headed` reaches e2e as `run -- --headed` and
 exits 2. Write `pnpm test:e2e --headed` or `pnpm exec e2e run --headed`.

package/skills/e2e/references/writing-tests.md

@@ -426,8 +426,10 @@ the app opens itself (`target="_blank"`, `window.open`) is not followed:
 - `waitForDownload(() => trigger, { timeout? })`: returns
   `{ path, absolutePath, suggestedFilename }`; `absolutePath` names the saved
   runner-side file for reading its contents, including with a hosted browser.
-- `keyboard.press(key)`, `keyboard.type(text)`, `mouse.*`: unfocused input;
-  prefer `locator.press` and `locator.fill`.
+- `keyboard.press(key)`, `keyboard.type(text)`, `keyboard.down(key)`,
+  `keyboard.up(key)`, `mouse.*`: unfocused input. Only `down(key)` holds a
+  key or modifier until `up(key)`. `press(key)` presses and releases within
+  the call. Prefer `locator.press` and `locator.fill`.
 
 A `route`, `unroute`, or `waitForResponse` pattern is a glob string or
 `RegExp` matched against the full URL (`*` stays within one path segment,