@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

package/dist/runtime/node-host-runtime-adapter.js

@@ -0,0 +1,285 @@
+import path from "node:path";
+import { ForgeFailureError } from "../session/session.types.js";
+import { withAspNetPrebuiltRunArguments } from "./aspnet-runtime-prebuild.js";
+import { hostPortEnvironment, } from "./host-runtime-contract.js";
+/**
+ * Launches an explicitly configured HTTP project command beneath the caller's
+ * attempt supervisor. It never shells a command and never promotes a project
+ * by framework detection alone.
+ */
+export class NodeHostRuntimeAdapter {
+    broker;
+    readinessTimeoutMs;
+    hardReadinessTimeoutMs;
+    readinessPollIntervalMs;
+    httpProbeTimeoutMs;
+    probeHttp;
+    constructor(broker, options = {}) {
+        this.broker = broker;
+        this.readinessTimeoutMs = boundedInteger(options.readinessTimeoutMs ?? 120_000, 100, 120_000, "readinessTimeoutMs");
+        this.hardReadinessTimeoutMs = boundedInteger(options.hardReadinessTimeoutMs ?? 600_000, this.readinessTimeoutMs, 900_000, "hardReadinessTimeoutMs");
+        this.readinessPollIntervalMs = boundedInteger(options.readinessPollIntervalMs ?? 100, 10, 5_000, "readinessPollIntervalMs");
+        this.httpProbeTimeoutMs = boundedInteger(options.httpProbeTimeoutMs ?? 1_000, 50, 10_000, "httpProbeTimeoutMs");
+        this.probeHttp = options.probeHttp ?? probeHttpReadiness;
+    }
+    async launch(owner, portConfig, command, launcher, signal) {
+        const framework = portConfig.adapter;
+        if (framework !== "node" && framework !== "vite" && framework !== "next" && framework !== "aspnetcore") {
+            throw new Error("node_runtime_adapter_invalid: port config must explicitly select node, vite, next, or aspnetcore.");
+        }
+        validateCommand(command);
+        if (!portConfig.baseUrlEnv || !portConfig.format) {
+            throw new Error("node_runtime_adapter_invalid: an HTTP baseUrlEnv and loopback format are required.");
+        }
+        let activeRequest = null;
+        const launched = await this.broker.launchWithRetry(owner, {
+            name: portConfig.name,
+            protocol: "tcp",
+        }, {
+            launch: async (port, launchSignal) => {
+                const request = buildNodeRuntimeLaunchRequest(framework, portConfig, command, port);
+                activeRequest = request;
+                return await launcher.launch(request, launchSignal);
+            },
+            verifyOwnership: async (value, _port, verifySignal) => {
+                if (!activeRequest)
+                    throw new Error("node_runtime_adapter_state: launch request was not recorded.");
+                return await this.waitUntilReady(value, activeRequest, launcher, verifySignal);
+            },
+            stop: launcher.stop,
+        }, signal);
+        if (!activeRequest)
+            throw new Error("node_runtime_adapter_state: active launch request is missing.");
+        return { ...launched, request: activeRequest };
+    }
+    async waitUntilReady(value, request, launcher, signal) {
+        const startedAt = Date.now();
+        const hardDeadline = startedAt + this.hardReadinessTimeoutMs;
+        let idleDeadline = startedAt + this.readinessTimeoutMs;
+        let outputRevision = -1;
+        let observedOwnership = "unbound";
+        while (Date.now() <= idleDeadline && Date.now() <= hardDeadline) {
+            if (signal?.aborted)
+                throw cancellationError(signal);
+            const diagnostics = await launcher.readinessDiagnostics?.(value);
+            if (diagnostics?.exited) {
+                throw new ForgeFailureError("host_runtime_process_exited", readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics), "bridge");
+            }
+            if (diagnostics?.outputRevision !== undefined && diagnostics.outputRevision > outputRevision) {
+                outputRevision = diagnostics.outputRevision;
+                idleDeadline = Math.min(hardDeadline, Date.now() + this.readinessTimeoutMs);
+            }
+            const ownership = await launcher.inspectListener(value, request, signal);
+            observedOwnership = ownership;
+            if (ownership === "foreign")
+                return false;
+            if (ownership === "owned" && await this.probeHttp(request.baseUrl, this.httpProbeTimeoutMs, signal)) {
+                return true;
+            }
+            await wait(this.readinessPollIntervalMs, signal);
+        }
+        const diagnostics = await launcher.readinessDiagnostics?.(value);
+        if (diagnostics?.exited) {
+            throw new ForgeFailureError("host_runtime_process_exited", readinessFailure("host_runtime_process_exited", `the supervised process exited with code ${diagnostics.exitCode ?? "unknown"} before its assigned runtime became ready`, request, diagnostics), "bridge");
+        }
+        const code = observedOwnership === "owned"
+            ? "host_runtime_http_readiness_timeout"
+            : "host_runtime_listener_timeout";
+        const reachedHardDeadline = Date.now() >= hardDeadline;
+        const detail = observedOwnership === "owned"
+            ? reachedHardDeadline
+                ? `the supervised process owned its assigned loopback port but HTTP readiness did not succeed within the ${this.hardReadinessTimeoutMs}ms hard limit`
+                : `the supervised process owned its assigned loopback port but made no readiness progress for ${this.readinessTimeoutMs}ms`
+            : reachedHardDeadline
+                ? `the supervised process did not bind its assigned loopback port within the ${this.hardReadinessTimeoutMs}ms hard limit`
+                : `the supervised process did not bind its assigned loopback port and made no output progress for ${this.readinessTimeoutMs}ms`;
+        throw new ForgeFailureError(code, readinessFailure(code, detail, request, diagnostics), "bridge");
+    }
+}
+function readinessFailure(code, detail, request, diagnostics) {
+    const evidence = [
+        boundedDiagnostic("stderr", diagnostics?.stderrTail),
+        boundedDiagnostic("stdout", diagnostics?.stdoutTail),
+    ].filter((value) => value !== null);
+    return `${code}: ${detail} (${request.baseUrl}).${evidence.length > 0 ? ` ${evidence.join(" ")}` : ""}`;
+}
+function boundedDiagnostic(label, value) {
+    const normalized = value?.replaceAll(/\s+/gu, " ").trim();
+    if (!normalized)
+        return null;
+    return `${label} tail: ${normalized.slice(-2_000)}`;
+}
+export function buildNodeRuntimeLaunchRequest(framework, portConfig, command, port) {
+    validateCommand(command);
+    if (port.hostIp !== "127.0.0.1" || port.protocol !== "tcp") {
+        throw new Error("node_runtime_adapter_invalid: project adapters require a TCP IPv4 loopback reservation.");
+    }
+    if (!portConfig.baseUrlEnv || !portConfig.format) {
+        throw new Error("node_runtime_adapter_invalid: an HTTP baseUrlEnv and loopback format are required.");
+    }
+    rejectConflictingFrameworkArguments(framework, command.args);
+    const portEnvironment = hostPortEnvironment(portConfig, port.hostIp, port.hostPort);
+    const baseUrl = portEnvironment[portConfig.baseUrlEnv];
+    if (!baseUrl)
+        throw new Error("node_runtime_adapter_invalid: base URL environment could not be rendered.");
+    const args = framework === "aspnetcore"
+        ? aspNetCoreArguments(command.command, command.args)
+        : [...command.args, ...frameworkArguments(framework, port.hostIp, port.hostPort)];
+    const adapterEnvironment = framework === "aspnetcore"
+        ? {
+            ASPNETCORE_URLS: baseUrl,
+            Hosting__Port: String(port.hostPort),
+            Harness__Reconciler__Hosted: "false",
+            Projects__RuntimeReadiness__Hosted: "false",
+            Runners__ServerLocalHeartbeat__Hosted: "false",
+            FORGE_RUNTIME_MODE: "host",
+            FORGE_DISPATCH_ATTEMPT_ID: port.dispatchAttemptId,
+            DOTNET_CLI_USE_MSBUILD_SERVER: "0",
+            DOTNET_NOLOGO: "1",
+        }
+        : { HOST: port.hostIp };
+    const forgeEnvironment = {
+        FORGE_RUNTIME_PORT_NAME: portConfig.name,
+        FORGE_RUNTIME_PORT: String(port.hostPort),
+        FORGE_RUNTIME_BASE_URL: baseUrl,
+    };
+    const expansionScope = {
+        ...command.environment,
+        ...portEnvironment,
+        ...adapterEnvironment,
+        ...forgeEnvironment,
+    };
+    return {
+        framework,
+        command: command.command,
+        args,
+        cwd: path.resolve(command.cwd),
+        environment: {
+            ...expandCommandEnvironment(command.environment, expansionScope),
+            ...portEnvironment,
+            ...adapterEnvironment,
+            ...forgeEnvironment,
+        },
+        port,
+        baseUrl,
+    };
+}
+function expandCommandEnvironment(environment, scope) {
+    return Object.fromEntries(Object.entries(environment ?? {}).map(([name, value]) => [
+        name,
+        value.replaceAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/gu, (_match, variable) => {
+            const resolved = scope[variable];
+            if (!resolved) {
+                throw new Error(`node_runtime_adapter_invalid: launch environment references unavailable variable '${variable}'.`);
+            }
+            return resolved;
+        }),
+    ]));
+}
+function frameworkArguments(framework, hostIp, hostPort) {
+    if (framework === "vite")
+        return ["--host", hostIp, "--port", String(hostPort), "--strictPort"];
+    if (framework === "next")
+        return ["--hostname", hostIp, "--port", String(hostPort)];
+    return [];
+}
+function rejectConflictingFrameworkArguments(framework, args) {
+    if (framework === "aspnetcore") {
+        const forbidden = new Set(["--urls", "--launch-profile", "-lp", "--no-launch-profile"]);
+        const conflict = args.find(argument => forbidden.has(argument)
+            || [...forbidden].some(flag => argument.startsWith(`${flag}=`)));
+        if (conflict) {
+            throw new Error(`node_runtime_adapter_invalid: command already supplies Forge-owned argument '${conflict}'.`);
+        }
+        return;
+    }
+    if (framework === "node")
+        return;
+    const forbidden = framework === "vite"
+        ? new Set(["--host", "--port", "--strictPort"])
+        : new Set(["--hostname", "--port", "-H", "-p"]);
+    const conflict = args.find(argument => forbidden.has(argument) || [...forbidden].some(flag => argument.startsWith(`${flag}=`)));
+    if (conflict) {
+        throw new Error(`node_runtime_adapter_invalid: command already supplies Forge-owned argument '${conflict}'.`);
+    }
+}
+function aspNetCoreArguments(command, args) {
+    const executable = path.basename(command).toLowerCase();
+    if (executable !== "dotnet" && executable !== "dotnet.exe") {
+        throw new Error("node_runtime_adapter_invalid: aspnetcore adapter requires the dotnet executable.");
+    }
+    if (args[0]?.toLowerCase() !== "run") {
+        throw new Error("node_runtime_adapter_invalid: aspnetcore adapter requires a dotnet run command.");
+    }
+    const prebuiltArgs = withAspNetPrebuiltRunArguments(command, args);
+    const applicationArguments = prebuiltArgs.indexOf("--");
+    const insertionIndex = applicationArguments < 0 ? prebuiltArgs.length : applicationArguments;
+    return [
+        ...prebuiltArgs.slice(0, insertionIndex),
+        "--disable-build-servers",
+        "-p:UseSharedCompilation=false",
+        "-p:DefaultItemExcludesInProjectFolder=TestResults/**",
+        "--no-launch-profile",
+        ...prebuiltArgs.slice(insertionIndex),
+    ];
+}
+function validateCommand(command) {
+    if (!boundedText(command.command, 1024)
+        || !path.isAbsolute(command.cwd)
+        || command.args.length > 128
+        || command.args.some(argument => !boundedText(argument, 4096))) {
+        throw new Error("node_runtime_adapter_invalid: command, arguments, or absolute working directory are invalid.");
+    }
+    for (const [name, value] of Object.entries(command.environment ?? {})) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u.test(name) || !boundedText(value, 8192)) {
+            throw new Error("node_runtime_adapter_invalid: command environment is invalid.");
+        }
+    }
+}
+async function probeHttpReadiness(url, timeoutMs, signal) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    try {
+        const response = await fetch(url, { redirect: "manual", signal: combined });
+        await response.body?.cancel().catch(() => undefined);
+        return true;
+    }
+    catch (_error) {
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        return false;
+    }
+}
+function wait(milliseconds, signal) {
+    if (signal?.aborted)
+        return Promise.reject(cancellationError(signal));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, milliseconds);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(cancellationError(signal));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+function boundedInteger(value, minimum, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`node_runtime_adapter_invalid: ${name} must be between ${minimum} and ${maximum}.`);
+    }
+    return value;
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every(character => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function cancellationError(signal) {
+    return new Error(String(signal?.reason ?? "Node runtime launch cancelled."));
+}

package/dist/runtime/pinned-directory-process.d.ts

@@ -0,0 +1,9 @@
+import type { BigIntStats } from "node:fs";
+export type PinnedDirectoryIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare class PinnedDirectoryProcessError extends Error {
+    readonly failureKind: "failed" | "timeout";
+    readonly terminationConfirmed: boolean;
+    constructor(message: string, failureKind: "failed" | "timeout", options?: ErrorOptions, terminationConfirmed?: boolean);
+}
+/** Keep filesystem stalls off the Bridge event loop. The worker pins and checks cwd. */
+export declare function runPinnedDirectoryProcess(parent: string, identity: PinnedDirectoryIdentity, worker: string, operation: object, bytes?: Buffer, maxBuffer?: number, timeoutMs?: number, terminationConfirmationMs?: number): Promise<string>;

package/dist/runtime/pinned-directory-process.js

@@ -0,0 +1,61 @@
+import childProcess from "node:child_process";
+export class PinnedDirectoryProcessError extends Error {
+    failureKind;
+    terminationConfirmed;
+    constructor(message, failureKind, options, terminationConfirmed = true) {
+        super(`pinned_directory_operation_${failureKind}: ${message}`, options);
+        this.failureKind = failureKind;
+        this.terminationConfirmed = terminationConfirmed;
+        this.name = "PinnedDirectoryProcessError";
+    }
+}
+/** Keep filesystem stalls off the Bridge event loop. The worker pins and checks cwd. */
+export async function runPinnedDirectoryProcess(parent, identity, worker, operation, bytes, maxBuffer = 16 * 1024, timeoutMs = 30_000, terminationConfirmationMs = 2_000) {
+    const environment = { ...process.env };
+    delete environment.NODE_OPTIONS;
+    const header = `${JSON.stringify({ parent, dev: identity.dev.toString(), ino: identity.ino.toString(), ...operation })}\n`;
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        const deadline = { timer: undefined };
+        const termination = { timer: undefined };
+        const child = childProcess.execFile(process.execPath, ["--input-type=commonjs", "-e", worker], {
+            cwd: parent, env: environment, windowsHide: true, maxBuffer,
+        }, (error, stdout, stderr) => {
+            if (settled)
+                return;
+            settled = true;
+            if (deadline.timer)
+                clearTimeout(deadline.timer);
+            if (termination.timer)
+                clearTimeout(termination.timer);
+            if (timedOut) {
+                reject(new PinnedDirectoryProcessError(`operation exceeded ${timeoutMs} ms`, "timeout", error ? { cause: error } : undefined));
+                return;
+            }
+            if (error) {
+                reject(new PinnedDirectoryProcessError(stderr.trim() || error.message, "failed", { cause: error }));
+            }
+            else
+                resolve(stdout);
+        });
+        deadline.timer = setTimeout(() => {
+            if (settled)
+                return;
+            timedOut = true;
+            child.kill("SIGKILL");
+            // Wait for execFile's callback so callers know the helper has released
+            // its pinned cwd before they remove attempt state. A mocked or wedged
+            // child still gets one bounded post-kill confirmation window.
+            termination.timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new PinnedDirectoryProcessError(`operation exceeded ${timeoutMs} ms and termination was not confirmed`, "timeout", undefined, false));
+            }, terminationConfirmationMs);
+        }, timeoutMs);
+        child.stdin.on("error", () => undefined);
+        child.stdin.write(header);
+        child.stdin.end(bytes);
+    });
+}

package/dist/runtime/pinned-source-directory.d.ts

@@ -0,0 +1,17 @@
+import { runPinnedDirectoryProcess, type PinnedDirectoryIdentity } from "./pinned-directory-process.js";
+export interface PinnedSourceEntry {
+    name: string;
+    kind: "directory" | "file" | "symlink" | "other";
+    identity: PinnedDirectoryIdentity;
+    size: bigint;
+}
+type PinnedDirectoryProcessRunner = typeof runPinnedDirectoryProcess;
+export interface PinnedSourceDirectoryReadOptions {
+    /** Production retries are Windows-only; tests may override this explicitly. */
+    readonly maxAttempts?: number;
+    readonly processRunner?: PinnedDirectoryProcessRunner;
+}
+/** Enumerate from a cwd whose inode is checked by the worker, not by reopening a validated pathname. */
+export declare function readPinnedSourceDirectory(directory: string, identity: PinnedDirectoryIdentity, timeoutMs?: number, terminationConfirmationMs?: number, options?: PinnedSourceDirectoryReadOptions): Promise<PinnedSourceEntry[]>;
+export declare function decodePinnedSourceDirectoryInventory(output: string): PinnedSourceEntry[];
+export {};

package/dist/runtime/pinned-source-directory.js

@@ -0,0 +1,94 @@
+import { PinnedDirectoryProcessError, runPinnedDirectoryProcess, } from "./pinned-directory-process.js";
+/** Enumerate from a cwd whose inode is checked by the worker, not by reopening a validated pathname. */
+export async function readPinnedSourceDirectory(directory, identity, timeoutMs = 30_000, terminationConfirmationMs = 2_000, options = {}) {
+    const configuredAttempts = options.maxAttempts ?? (process.platform === "win32" ? 2 : 1);
+    const maxAttempts = Math.max(1, Math.min(3, Math.floor(configuredAttempts), Math.floor(timeoutMs)));
+    const attemptBudgetMs = Math.max(1, Math.floor(timeoutMs / maxAttempts));
+    const attemptTerminationConfirmationMs = Math.min(Math.max(0, terminationConfirmationMs), Math.max(0, attemptBudgetMs - 1));
+    const attemptTimeoutMs = Math.max(1, attemptBudgetMs - attemptTerminationConfirmationMs);
+    const processRunner = options.processRunner ?? runPinnedDirectoryProcess;
+    let lastError;
+    let attemptsStarted = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        attemptsStarted = attempt;
+        try {
+            const output = await processRunner(directory, identity, worker, { kind: "source_inventory" }, undefined, 16 * 1024 * 1024, attemptTimeoutMs, attemptTerminationConfirmationMs);
+            return decodePinnedSourceDirectoryInventory(output);
+        }
+        catch (error) {
+            lastError = error;
+            if (!(error instanceof PinnedDirectoryProcessError)
+                || error.failureKind !== "timeout"
+                || !error.terminationConfirmed
+                || attempt === maxAttempts) {
+                break;
+            }
+        }
+    }
+    {
+        const error = lastError;
+        const detail = error instanceof Error ? error.message : String(error);
+        if (detail.includes("evidence inventory exceeds retention budget")) {
+            throw new Error("host_diagnostics_budget: evidence inventory exceeds retention budget.", { cause: error });
+        }
+        if (detail.includes("source directory identity changed") || detail.includes("invalid operation")) {
+            throw new Error(`host_diagnostics_source_invalid: pinned directory enumeration failed: ${detail}`, { cause: error });
+        }
+        const reason = error instanceof PinnedDirectoryProcessError && error.failureKind === "timeout"
+            ? `pinned directory enumeration timed out after ${attemptsStarted} attempt${attemptsStarted === 1 ? "" : "s"} within ${timeoutMs} ms recovery budget`
+            : "pinned directory enumeration was temporarily unavailable";
+        throw new Error(`host_diagnostics_temporary_unavailable: ${reason}: ${detail}`, { cause: error });
+    }
+}
+export function decodePinnedSourceDirectoryInventory(output) {
+    const decoded = JSON.parse(output);
+    if (!Array.isArray(decoded) || decoded.length > 10000) {
+        throw new Error("host_diagnostics_budget: evidence inventory exceeds retention budget.");
+    }
+    return decoded.map(entry => {
+        if (!isSingleComponent(entry.name) || !["directory", "file", "symlink", "other"].includes(entry.kind)
+            || !isSignedFileIdentity(entry.dev) || !isSignedFileIdentity(entry.ino) || !/^\d+$/u.test(entry.size)) {
+            throw new Error("host_diagnostics_source_invalid: invalid pinned directory inventory.");
+        }
+        return {
+            name: entry.name, kind: entry.kind, identity: { dev: BigInt(entry.dev), ino: BigInt(entry.ino) },
+            size: BigInt(entry.size),
+        };
+    }).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+}
+function isSignedFileIdentity(value) {
+    // Node exposes Windows FILE_ID_128 low words through signed bigint stat fields.
+    // A valid NTFS identity can therefore be negative when its high bit is set.
+    return /^-?\d{1,64}$/u.test(value);
+}
+function isSingleComponent(value) {
+    return Boolean(value) && value !== "." && value !== ".."
+        && !["/", ":", "\\", "\0"].some(character => value.includes(character));
+}
+const worker = String.raw `
+const fs = require('node:fs');
+const input = fs.readFileSync(0);
+const boundary = input.indexOf(10);
+const job = JSON.parse(input.subarray(0, boundary).toString('utf8'));
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const expected = { dev: BigInt(job.dev), ino: BigInt(job.ino) };
+const verify = () => {
+  const current = fs.statSync('.', { bigint: true });
+  if (!current.isDirectory() || !same(current, expected) || !samePath(fs.realpathSync('.'), job.parent))
+    throw new Error('source directory identity changed');
+};
+try {
+  if (job.kind !== 'source_inventory') throw new Error('invalid operation');
+  verify();
+  const entries = fs.readdirSync('.');
+  if (entries.length > 10000) throw new Error('evidence inventory exceeds retention budget');
+  const inventory = entries.map(name => {
+    const stat = fs.lstatSync(name, { bigint: true });
+    const kind = stat.isSymbolicLink() ? 'symlink' : stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
+    return { name, kind, dev: stat.dev.toString(), ino: stat.ino.toString(), size: stat.size.toString() };
+  });
+  verify();
+  process.stdout.write(JSON.stringify(inventory));
+} catch (error) { process.stderr.write(error.message); process.exitCode = 1; }
+`;

package/dist/runtime/playwright-host-runtime-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { HostRuntimePlaywrightConfig } from "./host-runtime-contract.js";
+export interface PlaywrightHostRuntimeContext {
+    readonly worktreePath: string;
+    readonly temporaryDirectory: string;
+    readonly testOutputDirectory: string;
+    readonly browserProfileDirectory: string;
+    readonly baseUrl: string;
+    readonly ownershipToken: string;
+}
+export interface PreparedPlaywrightHostRuntime {
+    readonly configPath: string;
+    readonly environment: Readonly<Record<string, string>>;
+}
+/**
+ * Prepares a finite Playwright test boundary for a managed-host attempt.
+ * The generated overlay points tests at Forge's verified listener, disables
+ * Playwright-managed web servers, and keeps writable artifacts attempt-local.
+ */
+export declare class PlaywrightHostRuntimeAdapter {
+    prepare(config: HostRuntimePlaywrightConfig, context: PlaywrightHostRuntimeContext): Promise<PreparedPlaywrightHostRuntime>;
+}