@tea-agent/loop-agent 0.27.1 → 0.28.0

package/dist/executors/pi-playwright-cli-tool.js

@@ -0,0 +1,955 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { appendFile, lstat, mkdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { processTreeSpawnOptions, terminateProcessTree } from "./process-tree.js";
+import { resolvePlaywrightCliLauncher } from "./playwright-cli-launcher.js";
+import { PLAYWRIGHT_CLI_ALLOWED_COMMANDS, isPlaywrightCliCommand, } from "../shared/playwright-cli-command-policy.js";
+export { PLAYWRIGHT_CLI_ALLOWED_COMMANDS, isPlaywrightCliCommand, };
+/** Logical capability name only; execution always uses the verified JS launcher. */
+export const PLAYWRIGHT_CLI_EXECUTABLE = "playwright-cli";
+export const PLAYWRIGHT_CLI_INTERACTION_COMMANDS = new Set([
+    "goto",
+    "snapshot",
+    "find",
+    "click",
+    "dblclick",
+    "fill",
+    "type",
+    "press",
+    "keydown",
+    "keyup",
+    "hover",
+    "select",
+    "check",
+    "uncheck",
+    "drag",
+    "drop",
+    "upload",
+    "go-back",
+    "go-forward",
+    "reload",
+    "dialog-accept",
+    "dialog-dismiss",
+    "resize",
+    "screenshot",
+    "pdf",
+    "console",
+    "requests",
+    "request",
+]);
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+const CONTROL_META = /(?:&&|\|\||[;|`$<>\n\r])/;
+const SESSION_FLAG = /^(?:-s(?:=|$)|--session(?:=|$))/;
+const OUTPUT_PATH_FLAGS = new Set([
+    "--filename",
+    "--path",
+    "--output",
+    "-o",
+    "--file",
+]);
+const SENSITIVE_COMMANDS = new Set(["fill", "type", "upload", "drop"]);
+function normalizePosix(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function isSafeRelativePosix(value) {
+    const normalized = normalizePosix(value);
+    if (!normalized || path.posix.isAbsolute(normalized) || path.win32.isAbsolute(normalized)) {
+        return false;
+    }
+    return normalized.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+export function redactPlaywrightCliArgs(command, args) {
+    return args.map((arg) => {
+        // Receipts are durable run evidence: do not retain selector/value ambiguity,
+        // sensitive source text, upload paths, or flag values for sensitive operations.
+        // Denied legacy page-script requests still receive the durable redaction
+        // treatment so a rejected request cannot leak source or credentials.
+        if (SENSITIVE_COMMANDS.has(command) || command === "eval")
+            return "<redacted>";
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(arg)) {
+            try {
+                const url = new URL(arg);
+                url.username = "";
+                url.password = "";
+                if (url.search)
+                    url.search = "";
+                if (url.hash)
+                    url.hash = "";
+                return url.toString();
+            }
+            catch {
+                return "<redacted-url>";
+            }
+        }
+        if (/(?:password|token|secret|authorization)=/i.test(arg)) {
+            return "<redacted-kv>";
+        }
+        return arg;
+    });
+}
+export function resolvePlaywrightCliReceiptPath(runDir, nodeId) {
+    return path.join(runDir, nodeId, "playwright-cli-receipt.jsonl");
+}
+export async function readPlaywrightCliReceipts(runDir, nodeId) {
+    const receiptPath = resolvePlaywrightCliReceiptPath(runDir, nodeId);
+    try {
+        const raw = await readFile(receiptPath, "utf8");
+        return raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+export function summarizePlaywrightCliReceipts(receipts) {
+    let hasSuccessfulOpen = false;
+    let hasInteractionOrAssertion = false;
+    let hasMeaningfulAssertion = false;
+    let hasCleanup = false;
+    let hasPostExecutionCleanup = false;
+    let sawOpen = false;
+    let sawMeaningfulAssertionAfterOpen = false;
+    let hasOrderedPassedReceiptChain = false;
+    let hasContiguousControllerSequence = true;
+    let previousSequence = 0;
+    const caseIds = new Set();
+    for (const receipt of receipts) {
+        caseIds.add(receipt.caseId);
+        const succeeded = receipt.exitCode === 0 && !receipt.timedOut;
+        const ordered = receipt.sequence === previousSequence + 1;
+        if (!ordered)
+            hasContiguousControllerSequence = false;
+        previousSequence = receipt.sequence;
+        if (receipt.command === "open" && succeeded) {
+            hasSuccessfulOpen = true;
+            if (ordered)
+                sawOpen = true;
+        }
+        if (PLAYWRIGHT_CLI_INTERACTION_COMMANDS.has(receipt.command) && succeeded) {
+            hasInteractionOrAssertion = true;
+        }
+        // A successful find is the only model-visible semantic assertion in v1.
+        if (receipt.command === "find" && succeeded) {
+            hasMeaningfulAssertion = true;
+            if (ordered && sawOpen)
+                sawMeaningfulAssertionAfterOpen = true;
+        }
+        if (receipt.controllerCleanup && succeeded) {
+            hasCleanup = true;
+            if (receipt.cleanupPhase === "post-execution") {
+                hasPostExecutionCleanup = true;
+                if (ordered && sawMeaningfulAssertionAfterOpen) {
+                    hasOrderedPassedReceiptChain = true;
+                }
+            }
+        }
+    }
+    return {
+        hasSuccessfulOpen,
+        hasInteractionOrAssertion,
+        hasMeaningfulAssertion,
+        hasCleanup,
+        hasPostExecutionCleanup,
+        hasOrderedPassedReceiptChain: hasOrderedPassedReceiptChain && hasContiguousControllerSequence,
+        caseIds,
+    };
+}
+function assertNoControlMeta(arg) {
+    if (CONTROL_META.test(arg)) {
+        throw new PlaywrightCliPolicyError("shell-control-meta", `argument contains shell control metacharacters: ${arg}`);
+    }
+    if (arg.includes("\0")) {
+        throw new PlaywrightCliPolicyError("nul-byte", "argument contains NUL byte");
+    }
+}
+function assertNoSessionFlag(arg) {
+    if (SESSION_FLAG.test(arg) || arg === "--session" || arg.startsWith("--session=")) {
+        throw new PlaywrightCliPolicyError("named-session-forbidden", "named browser sessions are forbidden; use the default session only");
+    }
+}
+function isProductionHost(hostname) {
+    const host = hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1")
+        return false;
+    if (host.endsWith(".local") || host.endsWith(".test") || host.endsWith(".localhost")) {
+        return false;
+    }
+    return /(?:^|\.)prod(?:uction)?(?:\.|$)/i.test(host) || /(?:^|\.)(?:www\.)?[^.]*(?:prod|production)/i.test(host);
+}
+function validateOpenArgs(args, baseUrl) {
+    const flags = new Set();
+    let url;
+    const normalized = [];
+    for (const arg of args) {
+        assertNoControlMeta(arg);
+        assertNoSessionFlag(arg);
+        if (arg === "--browser=chrome" || arg === "--headed") {
+            flags.add(arg);
+            normalized.push(arg);
+            continue;
+        }
+        if (arg.startsWith("--browser=") || arg === "--browser" || arg === "--headless") {
+            throw new PlaywrightCliPolicyError("open-browser-flags", "open must use --browser=chrome --headed only");
+        }
+        if (/^[a-z][a-z0-9+.-]*:/i.test(arg) || arg.startsWith("http")) {
+            url = arg;
+            continue;
+        }
+        throw new PlaywrightCliPolicyError("open-args", `unsupported open argument: ${arg}`);
+    }
+    if (!flags.has("--browser=chrome") || !flags.has("--headed")) {
+        // controller injects required flags when missing from model args
+        if (!flags.has("--browser=chrome"))
+            normalized.unshift("--browser=chrome");
+        if (!flags.has("--headed"))
+            normalized.push("--headed");
+    }
+    if (!url) {
+        throw new PlaywrightCliPolicyError("open-url-required", "open requires an absolute http(s) URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new PlaywrightCliPolicyError("open-url-invalid", `invalid open URL: ${url}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new PlaywrightCliPolicyError("open-url-scheme", `open URL scheme must be http(s); got ${parsed.protocol}`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new PlaywrightCliPolicyError("open-url-credentials", "open URL must not include credentials");
+    }
+    if (isProductionHost(parsed.hostname)) {
+        throw new PlaywrightCliPolicyError("open-url-production", `production host forbidden: ${parsed.hostname}`);
+    }
+    let frozen;
+    try {
+        frozen = new URL(baseUrl ?? "");
+    }
+    catch {
+        throw new PlaywrightCliPolicyError("base-url-invalid", "controller-owned baseUrl is invalid or missing");
+    }
+    if (frozen.protocol !== "http:" && frozen.protocol !== "https:") {
+        throw new PlaywrightCliPolicyError("base-url-invalid", "controller-owned baseUrl must be http(s)");
+    }
+    if (parsed.origin !== frozen.origin) {
+        throw new PlaywrightCliPolicyError("open-url-origin", `open URL origin ${parsed.origin} must match frozen baseUrl origin ${frozen.origin}`);
+    }
+    normalized.push(parsed.toString());
+    return normalized;
+}
+function resolveEvidenceRelative(rawPath, ctx) {
+    const evidenceDir = normalizePosix(ctx.evidenceDir).replace(/\/$/, "");
+    const evidencePrefix = `testcase/frontend/evidence/${ctx.caseId}`;
+    if (!(evidenceDir === evidencePrefix || evidenceDir.startsWith(`${evidencePrefix}/`))) {
+        throw new PlaywrightCliPolicyError("evidence-dir-invalid", `evidenceDir must be under ${evidencePrefix}`);
+    }
+    const candidate = normalizePosix(rawPath);
+    if (!candidate || candidate.includes("\0")) {
+        throw new PlaywrightCliPolicyError("path-empty", "empty output path");
+    }
+    if (path.win32.isAbsolute(candidate) || path.posix.isAbsolute(candidate) || /^[a-zA-Z]:\//.test(candidate)) {
+        throw new PlaywrightCliPolicyError("path-absolute", "absolute output paths are forbidden");
+    }
+    if (candidate.split("/").includes("..")) {
+        throw new PlaywrightCliPolicyError("path-traversal", "path traversal is forbidden");
+    }
+    // Simple relative filename → rewrite into evidenceDir
+    if (!candidate.includes("/")) {
+        return `${evidenceDir}/${candidate}`;
+    }
+    if (candidate.startsWith(`${evidenceDir}/`) || candidate === evidenceDir) {
+        return candidate;
+    }
+    if (candidate.startsWith("testcase/frontend/evidence/") && !candidate.startsWith(`${evidencePrefix}/`)) {
+        throw new PlaywrightCliPolicyError("path-cross-case", "output path escapes current case evidenceDir");
+    }
+    throw new PlaywrightCliPolicyError("path-outside-evidence", `output path must stay under ${evidenceDir}`);
+}
+function resolveScreenshotFilename(rawFilename, ctx) {
+    if (!rawFilename) {
+        throw new PlaywrightCliPolicyError("screenshot-filename-empty", "screenshot --filename requires a non-empty filename");
+    }
+    try {
+        const resolved = resolveEvidenceRelative(rawFilename, ctx);
+        if (resolved === normalizePosix(ctx.evidenceDir).replace(/\/$/, "")) {
+            throw new PlaywrightCliPolicyError("screenshot-filename-unsafe", "screenshot --filename must name a file within the current case evidence directory");
+        }
+        return resolved;
+    }
+    catch (error) {
+        if (error instanceof PlaywrightCliPolicyError &&
+            error.code === "evidence-dir-invalid") {
+            throw error;
+        }
+        throw new PlaywrightCliPolicyError("screenshot-filename-unsafe", "screenshot filename must stay within the current case evidence directory");
+    }
+}
+function isSafeBareScreenshotFilename(value) {
+    return (!value.includes("/") &&
+        !value.includes("\\") &&
+        isSafeRelativePosix(value));
+}
+function isPlaywrightCliElementRef(value) {
+    return /^e[1-9]\d*$/.test(value);
+}
+/**
+ * `playwright-cli screenshot [target]` accepts its output only through
+ * `--filename <file>`. Legacy single filenames are normalized rather than
+ * forwarded as positional targets; all other forms are fail-closed.
+ */
+function normalizeScreenshotArgs(args, ctx) {
+    let target;
+    let filename;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--filename") {
+            if (filename !== undefined) {
+                throw new PlaywrightCliPolicyError("screenshot-filename-duplicate", "screenshot accepts exactly one --filename");
+            }
+            const value = args[index + 1];
+            if (value === undefined) {
+                throw new PlaywrightCliPolicyError("screenshot-filename-missing", "screenshot --filename requires a value");
+            }
+            if (value === "--filename" || value.startsWith("--filename=")) {
+                throw new PlaywrightCliPolicyError("screenshot-filename-duplicate", "screenshot accepts exactly one --filename");
+            }
+            if (value.startsWith("-")) {
+                throw new PlaywrightCliPolicyError("screenshot-filename-missing", "screenshot --filename requires a value");
+            }
+            filename = resolveScreenshotFilename(value, ctx);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--filename=")) {
+            if (filename !== undefined) {
+                throw new PlaywrightCliPolicyError("screenshot-filename-duplicate", "screenshot accepts exactly one --filename");
+            }
+            filename = resolveScreenshotFilename(arg.slice("--filename=".length), ctx);
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new PlaywrightCliPolicyError("screenshot-args-ambiguous", "screenshot accepts only an optional target and --filename");
+        }
+        if (target !== undefined) {
+            throw new PlaywrightCliPolicyError("screenshot-args-ambiguous", "screenshot accepts at most one target");
+        }
+        target = arg;
+    }
+    if (filename === undefined) {
+        if (!target || !isSafeBareScreenshotFilename(target)) {
+            throw new PlaywrightCliPolicyError("screenshot-filename-unsafe", "legacy screenshot input must be one safe bare filename");
+        }
+        filename = resolveScreenshotFilename(target, ctx);
+        target = undefined;
+    }
+    else if (target !== undefined && !isPlaywrightCliElementRef(target)) {
+        throw new PlaywrightCliPolicyError("screenshot-target-invalid", "screenshot target must be a real element ref such as e5");
+    }
+    return target ? [target, "--filename", filename] : ["--filename", filename];
+}
+function normalizePdfOrSnapshotArgs(command, args, ctx) {
+    let target;
+    let filename;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--filename" || arg.startsWith("--filename=")) {
+            if (filename !== undefined) {
+                throw new PlaywrightCliPolicyError("output-filename-duplicate", `${command} accepts exactly one --filename`);
+            }
+            const value = arg === "--filename" ? args[++index] : arg.slice("--filename=".length);
+            if (value === undefined || value.startsWith("-")) {
+                throw new PlaywrightCliPolicyError("output-filename-missing", `${command} --filename requires a value`);
+            }
+            if (!value) {
+                throw new PlaywrightCliPolicyError("output-filename-empty", `${command} --filename requires a non-empty filename`);
+            }
+            try {
+                filename = resolveEvidenceRelative(value, ctx);
+            }
+            catch {
+                throw new PlaywrightCliPolicyError("output-filename-unsafe", `${command} filename must stay within the current case evidence directory`);
+            }
+            if (filename === normalizePosix(ctx.evidenceDir).replace(/\/$/, "")) {
+                throw new PlaywrightCliPolicyError("output-filename-unsafe", `${command} --filename must name a file`);
+            }
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new PlaywrightCliPolicyError("output-args-ambiguous", `${command} accepts only an optional target and --filename`);
+        }
+        if (target !== undefined || command === "pdf") {
+            throw new PlaywrightCliPolicyError("output-args-ambiguous", `${command} accepts no positional output path`);
+        }
+        target = arg;
+    }
+    if (filename === undefined) {
+        if (command === "snapshot" && (target === undefined || isPlaywrightCliElementRef(target))) {
+            return target ? [target] : [];
+        }
+        throw new PlaywrightCliPolicyError("output-filename-required", `${command} requires --filename <file>`);
+    }
+    if (target !== undefined && !isPlaywrightCliElementRef(target)) {
+        throw new PlaywrightCliPolicyError("output-target-invalid", `${command} target must be a real element ref such as e5`);
+    }
+    return target ? [target, "--filename", filename] : ["--filename", filename];
+}
+function rewriteArgsForPaths(command, args, ctx) {
+    const inputCommands = new Set(["upload", "drop"]);
+    const rewritten = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        assertNoControlMeta(arg);
+        assertNoSessionFlag(arg);
+        const eq = arg.match(/^(--?(?:filename|path|output|file|o))=(.*)$/i);
+        if (eq) {
+            if (!inputCommands.has(command)) {
+                throw new PlaywrightCliPolicyError("output-flag-forbidden", "file output flags are not supported for this command");
+            }
+            assertInputPathAllowed(eq[2], ctx);
+            rewritten.push(`${eq[1]}=${normalizePosix(eq[2])}`);
+            continue;
+        }
+        const bareFlag = arg.toLowerCase();
+        if (OUTPUT_PATH_FLAGS.has(bareFlag)) {
+            const value = args[i + 1];
+            if (value === undefined) {
+                throw new PlaywrightCliPolicyError("output-flag-value-missing", "file path flag requires a value");
+            }
+            if (!inputCommands.has(command)) {
+                throw new PlaywrightCliPolicyError("output-flag-forbidden", "file output flags are not supported for this command");
+            }
+            assertNoControlMeta(value);
+            assertNoSessionFlag(value);
+            assertInputPathAllowed(value, ctx);
+            rewritten.push(arg, normalizePosix(value));
+            i += 1;
+            continue;
+        }
+        if (inputCommands.has(command) && !arg.startsWith("-") && /\.[a-z0-9]+$/i.test(arg)) {
+            assertInputPathAllowed(arg, ctx);
+            rewritten.push(normalizePosix(arg));
+            continue;
+        }
+        rewritten.push(arg);
+    }
+    return rewritten;
+}
+function assertInputPathAllowed(rawPath, ctx) {
+    const candidate = normalizePosix(rawPath);
+    if (!isSafeRelativePosix(candidate)) {
+        throw new PlaywrightCliPolicyError("input-path-unsafe", `unsafe input path: ${rawPath}`);
+    }
+    const allowedPrefixes = [
+        `testcase/frontend/evidence/${ctx.caseId}/`,
+        "testcase/frontend/cases/",
+        "testcase/frontend/rag/",
+        "testcase/frontend/fixtures/",
+    ];
+    if (!allowedPrefixes.some((prefix) => candidate === prefix.slice(0, -1) || candidate.startsWith(prefix)) &&
+        !candidate.startsWith(normalizePosix(ctx.evidenceDir) + "/")) {
+        throw new PlaywrightCliPolicyError("input-path-outside", `input path outside allowed case/RAG/fixture/evidence roots: ${rawPath}`);
+    }
+}
+export class PlaywrightCliPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PlaywrightCliPolicyError";
+        this.code = code;
+    }
+}
+export function preparePlaywrightCliArgv(input, ctx) {
+    const command = String(input.command ?? "").trim();
+    if (!isPlaywrightCliCommand(command)) {
+        throw new PlaywrightCliPolicyError("command-not-allowed", `playwright-cli command not allowed: ${command || "(empty)"}`);
+    }
+    const rawArgs = Array.isArray(input.args) ? input.args.map(String) : [];
+    for (const arg of rawArgs) {
+        assertNoControlMeta(arg);
+        assertNoSessionFlag(arg);
+    }
+    let args = rawArgs;
+    if (command === "open") {
+        args = validateOpenArgs(rawArgs, ctx.baseUrl);
+    }
+    else if (command === "goto") {
+        args = rawArgs.map((arg) => {
+            assertNoControlMeta(arg);
+            assertNoSessionFlag(arg);
+            if (arg.startsWith("-")) {
+                throw new PlaywrightCliPolicyError("goto-args", "goto accepts one URL and no flags");
+            }
+            let target;
+            try {
+                target = new URL(arg, ctx.baseUrl).toString();
+            }
+            catch {
+                throw new PlaywrightCliPolicyError("goto-url-invalid", "goto requires a URL relative to the controller baseUrl");
+            }
+            const openLike = validateOpenArgs(["--browser=chrome", "--headed", target], ctx.baseUrl);
+            return openLike[openLike.length - 1];
+        });
+        if (args.length !== 1) {
+            throw new PlaywrightCliPolicyError("goto-args", "goto requires exactly one URL");
+        }
+    }
+    else if (command === "screenshot") {
+        args = normalizeScreenshotArgs(rawArgs, ctx);
+    }
+    else if (command === "pdf" || command === "snapshot") {
+        args = normalizePdfOrSnapshotArgs(command, rawArgs, ctx);
+    }
+    else {
+        args = rewriteArgsForPaths(command, rawArgs, ctx);
+    }
+    return { command, args };
+}
+/** Validate upload/drop input using real paths; symlinks and repository-root fallback fail closed. */
+async function validatePlaywrightCliInputFiles(command, args, ctx) {
+    if (command !== "upload" && command !== "drop")
+        return;
+    if (!ctx.inputRoot) {
+        throw new PlaywrightCliPolicyError("input-root-missing", "upload/drop requires a controller-owned inputRoot");
+    }
+    const root = await realpath(path.resolve(ctx.repoRoot, ctx.inputRoot));
+    // The structured CLI syntax carries element references plus one or more file
+    // paths.  Only file-shaped operands are filesystem inputs; selectors never
+    // receive a repository-root fallback.  No file operand is fail-closed.
+    const candidates = args.filter((arg) => !arg.startsWith("-") && /\.[A-Za-z0-9]{1,16}$/.test(arg));
+    if (candidates.length === 0) {
+        throw new PlaywrightCliPolicyError("input-path-missing", "upload/drop requires an explicit file path under inputRoot");
+    }
+    for (const candidate of candidates) {
+        if (!isSafeRelativePosix(candidate)) {
+            throw new PlaywrightCliPolicyError("input-path-unsafe", "upload/drop input must be a safe path relative to inputRoot");
+        }
+        const lexical = path.resolve(ctx.repoRoot, candidate);
+        const relative = path.relative(root, lexical);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new PlaywrightCliPolicyError("input-path-outside", "upload/drop input escapes inputRoot");
+        }
+        const info = await lstat(lexical);
+        if (!info.isFile() || info.isSymbolicLink()) {
+            throw new PlaywrightCliPolicyError("input-not-regular-file", "upload/drop input must be a regular non-symlink file");
+        }
+        const resolved = await realpath(lexical);
+        const resolvedRelative = path.relative(root, resolved);
+        if (resolvedRelative.startsWith("..") || path.isAbsolute(resolvedRelative)) {
+            throw new PlaywrightCliPolicyError("input-realpath-escape", "upload/drop input realpath escapes inputRoot");
+        }
+        if (!(await stat(resolved)).isFile()) {
+            throw new PlaywrightCliPolicyError("input-not-regular-file", "upload/drop input must resolve to a regular file");
+        }
+    }
+}
+function pathIsContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return !(relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative));
+}
+function outputRealpathUnsafe(message) {
+    return new PlaywrightCliPolicyError("output-realpath-unsafe", message);
+}
+async function lstatOutputPath(candidate) {
+    try {
+        return await lstat(candidate);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw outputRealpathUnsafe(`cannot inspect output path: ${candidate}`);
+    }
+}
+function canonicalOutputFilename(command, args) {
+    if (command !== "screenshot" && command !== "pdf" && command !== "snapshot") {
+        return undefined;
+    }
+    const index = args.indexOf("--filename");
+    if (index < 0) {
+        if (command === "snapshot")
+            return undefined;
+        throw outputRealpathUnsafe("output command is missing canonical --filename argv");
+    }
+    const filename = args[index + 1];
+    if (!filename || index !== args.length - 2) {
+        throw outputRealpathUnsafe("output command did not produce canonical --filename argv");
+    }
+    return filename;
+}
+/**
+ * Verify controller-owned output paths immediately before runner/launcher use.
+ * This rejects pre-existing symlinks and validates both lexical and realpath
+ * containment; it intentionally cannot eliminate a post-check filesystem race.
+ */
+async function validatePlaywrightCliOutputPath(command, args, ctx) {
+    const outputFilename = canonicalOutputFilename(command, args);
+    if (!outputFilename)
+        return;
+    const repoRoot = path.resolve(ctx.repoRoot);
+    const caseEvidenceRoot = path.resolve(repoRoot, "testcase", "frontend", "evidence", ctx.caseId);
+    const evidenceDir = path.resolve(repoRoot, ctx.evidenceDir);
+    const target = path.resolve(repoRoot, outputFilename);
+    if (!pathIsContained(repoRoot, caseEvidenceRoot) ||
+        !pathIsContained(caseEvidenceRoot, evidenceDir) ||
+        !pathIsContained(evidenceDir, target) ||
+        target === evidenceDir) {
+        throw outputRealpathUnsafe("output path escapes the current case evidence directory");
+    }
+    for (const directory of [repoRoot, caseEvidenceRoot, evidenceDir]) {
+        const info = await lstatOutputPath(directory);
+        if (!info || info.isSymbolicLink() || !info.isDirectory()) {
+            throw outputRealpathUnsafe("output evidence directory must be an existing non-symlink directory");
+        }
+    }
+    const relativeParts = path.relative(repoRoot, target).split(path.sep).filter(Boolean);
+    let current = repoRoot;
+    let nearestExistingDirectory = repoRoot;
+    let targetExists = false;
+    for (let index = 0; index < relativeParts.length; index += 1) {
+        current = path.join(current, relativeParts[index]);
+        const info = await lstatOutputPath(current);
+        if (!info)
+            break;
+        if (info.isSymbolicLink()) {
+            throw outputRealpathUnsafe("output path has a symlink ancestor or target");
+        }
+        if (index === relativeParts.length - 1) {
+            targetExists = true;
+            if (!info.isFile()) {
+                throw outputRealpathUnsafe("output target must be a regular file when it exists");
+            }
+            break;
+        }
+        if (!info.isDirectory()) {
+            throw outputRealpathUnsafe("output path has a non-directory ancestor");
+        }
+        nearestExistingDirectory = current;
+    }
+    let repoReal;
+    let caseEvidenceReal;
+    let evidenceReal;
+    let nearestExistingReal;
+    try {
+        [repoReal, caseEvidenceReal, evidenceReal, nearestExistingReal] = await Promise.all([
+            realpath(repoRoot),
+            realpath(caseEvidenceRoot),
+            realpath(evidenceDir),
+            realpath(nearestExistingDirectory),
+        ]);
+    }
+    catch {
+        throw outputRealpathUnsafe("cannot resolve output containment realpath");
+    }
+    if (!pathIsContained(repoReal, caseEvidenceReal) ||
+        !pathIsContained(repoReal, evidenceReal) ||
+        !pathIsContained(caseEvidenceReal, evidenceReal) ||
+        !pathIsContained(evidenceReal, nearestExistingReal)) {
+        throw outputRealpathUnsafe("output realpath escapes the current case evidence directory");
+    }
+    if (targetExists) {
+        let targetReal;
+        try {
+            targetReal = await realpath(target);
+        }
+        catch {
+            throw outputRealpathUnsafe("cannot resolve existing output target realpath");
+        }
+        if (!pathIsContained(evidenceReal, targetReal) || !pathIsContained(repoReal, targetReal)) {
+            throw outputRealpathUnsafe("existing output target realpath escapes containment");
+        }
+    }
+}
+export async function defaultPlaywrightCliCommandRunner(input) {
+    const maxBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    return await new Promise((resolve) => {
+        const child = spawn(input.executable, input.argv, {
+            cwd: input.cwd,
+            env: input.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            ...processTreeSpawnOptions(),
+        });
+        let stdout = "";
+        let stderr = "";
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        let timedOut = false;
+        const finish = (exitCode, signalName) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (input.signal)
+                input.signal.removeEventListener("abort", onAbort);
+            resolve({
+                exitCode,
+                stdout,
+                stderr,
+                timedOut,
+                signal: signalName ?? null,
+            });
+        };
+        const onAbort = () => {
+            timedOut = false;
+            terminateProcessTree(child, "SIGKILL");
+            finish(null, "abort");
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminateProcessTree(child, "SIGKILL");
+        }, input.timeoutMs);
+        if (input.signal) {
+            if (input.signal.aborted)
+                onAbort();
+            else
+                input.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        child.stdout?.on("data", (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (stdoutBytes >= maxBytes)
+                return;
+            const slice = buf.subarray(0, Math.max(0, maxBytes - stdoutBytes));
+            stdoutBytes += slice.length;
+            stdout += slice.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (stderrBytes >= maxBytes)
+                return;
+            const slice = buf.subarray(0, Math.max(0, maxBytes - stderrBytes));
+            stderrBytes += slice.length;
+            stderr += slice.toString("utf8");
+        });
+        child.on("error", (error) => {
+            stderr = stderr || error.message;
+            finish(null, null);
+        });
+        child.on("close", (code, signalName) => {
+            finish(code, signalName);
+        });
+    });
+}
+let receiptSequenceByNode = new Map();
+/** Test hook: reset per-node receipt sequence counters. */
+export function resetPlaywrightCliReceiptSequencesForTests() {
+    receiptSequenceByNode = new Map();
+}
+async function appendReceipt(ctx, receipt) {
+    const receiptPath = resolvePlaywrightCliReceiptPath(ctx.runDir, ctx.nodeId);
+    await mkdir(path.dirname(receiptPath), { recursive: true });
+    await appendFile(receiptPath, `${JSON.stringify(receipt)}\n`, "utf8");
+}
+function nextSequence(nodeId) {
+    const current = receiptSequenceByNode.get(nodeId) ?? 0;
+    const next = current + 1;
+    receiptSequenceByNode.set(nodeId, next);
+    return next;
+}
+export async function executePlaywrightCliCommand(input, ctx, signal) {
+    const startedAt = new Date();
+    const sequence = nextSequence(ctx.nodeId);
+    const timeoutSeconds = Math.max(1, Math.min(600, Number(input.timeoutSeconds ?? ctx.defaultTimeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) ||
+        DEFAULT_TIMEOUT_SECONDS));
+    let command = String(input.command ?? "");
+    let args = [];
+    let errorClass;
+    try {
+        const prepared = preparePlaywrightCliArgv(input, ctx);
+        command = prepared.command;
+        args = prepared.args;
+    }
+    catch (error) {
+        errorClass =
+            error instanceof PlaywrightCliPolicyError ? error.code : "prepare-failed";
+        const finishedAt = new Date();
+        const receipt = {
+            schemaVersion: 1,
+            caseId: ctx.caseId,
+            sequence,
+            command,
+            argsRedacted: redactPlaywrightCliArgs(command, Array.isArray(input.args) ? input.args.map(String) : []),
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            exitCode: null,
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            outputSha256: createHash("sha256").update("").digest("hex"),
+            toolVersion: ctx.toolVersion ?? "unknown",
+            errorClass,
+        };
+        await appendReceipt(ctx, receipt);
+        return {
+            ok: false,
+            exitCode: null,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            timedOut: false,
+            receipt,
+            errorClass,
+        };
+    }
+    let executable = PLAYWRIGHT_CLI_EXECUTABLE;
+    let argv = [command, ...args];
+    try {
+        await validatePlaywrightCliOutputPath(command, args, ctx);
+        await validatePlaywrightCliInputFiles(command, args, ctx);
+        // Test runners are an in-memory boundary and never spawn; production always
+        // resolves the verified JavaScript launcher rather than a PATH/.cmd shim.
+        if (!ctx.runCommand) {
+            const launcher = resolvePlaywrightCliLauncher(ctx.repoRoot);
+            executable = launcher.executable;
+            argv = [...launcher.argvPrefix, command, ...args];
+        }
+    }
+    catch (error) {
+        errorClass = error instanceof PlaywrightCliPolicyError ? error.code : "playwright-cli-unavailable";
+        const finishedAt = new Date();
+        const receipt = {
+            schemaVersion: 1, caseId: ctx.caseId, sequence, command,
+            argsRedacted: redactPlaywrightCliArgs(command, args), startedAt: startedAt.toISOString(), finishedAt: finishedAt.toISOString(),
+            exitCode: null, durationMs: finishedAt.getTime() - startedAt.getTime(), outputSha256: createHash("sha256").update("").digest("hex"), toolVersion: ctx.toolVersion ?? "unknown", errorClass,
+        };
+        await appendReceipt(ctx, receipt);
+        return { ok: false, exitCode: null, stdout: "", stderr: error instanceof Error ? error.message : String(error), timedOut: false, receipt, errorClass };
+    }
+    const runner = ctx.runCommand ?? defaultPlaywrightCliCommandRunner;
+    let runResult;
+    try {
+        runResult = await runner({
+            executable,
+            argv,
+            cwd: path.resolve(ctx.repoRoot),
+            timeoutMs: timeoutSeconds * 1000,
+            signal,
+            env: {
+                ...process.env,
+                CI: process.env.CI ?? "1",
+            },
+        });
+    }
+    catch (error) {
+        runResult = { exitCode: null, stdout: "", stderr: error instanceof Error ? error.message : String(error), timedOut: false, signal: null };
+    }
+    const finishedAt = new Date();
+    const combined = `${runResult.stdout}\n${runResult.stderr}`;
+    const receipt = {
+        schemaVersion: 1,
+        caseId: ctx.caseId,
+        sequence,
+        command,
+        argsRedacted: redactPlaywrightCliArgs(command, args),
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        exitCode: runResult.exitCode,
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        outputSha256: createHash("sha256").update(combined).digest("hex"),
+        toolVersion: ctx.toolVersion ?? "unknown",
+        timedOut: runResult.timedOut || undefined,
+        errorClass: runResult.timedOut
+            ? "timeout"
+            : runResult.signal === "abort"
+                ? "abort"
+                : runResult.exitCode === 0
+                    ? undefined
+                    : "nonzero-exit",
+    };
+    await appendReceipt(ctx, receipt);
+    return {
+        ok: runResult.exitCode === 0 && !runResult.timedOut,
+        exitCode: runResult.exitCode,
+        stdout: runResult.stdout,
+        stderr: runResult.stderr,
+        timedOut: runResult.timedOut,
+        receipt,
+        errorClass: receipt.errorClass,
+    };
+}
+/**
+ * Best-effort default-session close for child finally / pre-start cleanup.
+ * Missing session must not throw.
+ */
+export async function cleanupPlaywrightCliDefaultSession(ctx, signal, cleanupPhase = "post-execution") {
+    // Best-effort: missing/no-op session must not throw to callers.
+    const result = await executePlaywrightCliCommand({ command: "close", args: [] }, ctx, signal);
+    // Persist the controller-owned lifecycle phase for every cleanup attempt so
+    // timeout/abort/spawn/nonzero failures remain auditable. Only a successful
+    // marker is treated as cleanup-confirmed by summarizePlaywrightCliReceipts.
+    const marker = {
+        ...result.receipt,
+        sequence: nextSequence(ctx.nodeId),
+        controllerCleanup: true,
+        cleanupPhase,
+    };
+    await appendReceipt(ctx, marker);
+    return { ...result, receipt: marker };
+}
+/**
+ * Structured custom tool for Pi SDK. Model only passes {command, args?, timeoutSeconds?}.
+ */
+export async function createPlaywrightCliTool(ctx) {
+    const [{ Type }, { defineTool }] = await Promise.all([
+        import("typebox"),
+        import("@earendil-works/pi-coding-agent"),
+    ]);
+    const parameters = Type.Object({
+        command: Type.String({
+            description: `Playwright CLI command name. Allowed: ${PLAYWRIGHT_CLI_ALLOWED_COMMANDS.join(", ")}`,
+        }),
+        args: Type.Optional(Type.Array(Type.String(), { description: "Positional/flag args (not a shell string)" })),
+        timeoutSeconds: Type.Optional(Type.Number({ description: "Per-command timeout seconds (default 60, max 600)" })),
+    }, { additionalProperties: false });
+    return defineTool({
+        name: "playwright_cli",
+        label: "playwright_cli",
+        description: "Execute a controlled playwright-cli command. Fixed executable; no shell chaining. Use for open/snapshot/interaction/close only.",
+        parameters,
+        async execute(_toolCallId, params, signal, _onUpdate, _extensionContext) {
+            const result = await executePlaywrightCliCommand(params, ctx, signal);
+            const text = [
+                `ok=${result.ok}`,
+                `command=${result.receipt.command}`,
+                `exitCode=${result.exitCode}`,
+                result.timedOut ? "timedOut=true" : "",
+                result.errorClass ? `errorClass=${result.errorClass}` : "",
+                result.stdout ? `stdout:\n${result.stdout}` : "",
+                result.stderr ? `stderr:\n${result.stderr}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+            return {
+                content: [{ type: "text", text }],
+                details: result,
+            };
+        },
+    });
+}
+export const PI_COMMAND_CAPABILITY_REGISTRY = {
+    "playwright-cli": createPlaywrightCliTool,
+};
+export function resolveCaseIdFromWriteSet(writeSet) {
+    for (const entry of writeSet ?? []) {
+        const normalized = normalizePosix(entry);
+        const match = normalized.match(/^testcase\/frontend\/evidence\/([^/]+)(?:\/\*\*)?$/);
+        if (match?.[1] && match[1] !== "**" && match[1] !== "*") {
+            return match[1];
+        }
+        const nested = normalized.match(/^testcase\/frontend\/evidence\/([^/]+)\//);
+        if (nested?.[1])
+            return nested[1];
+    }
+    return undefined;
+}
+export function resolveEvidenceDirFromWriteSet(writeSet) {
+    const caseId = resolveCaseIdFromWriteSet(writeSet);
+    if (!caseId)
+        return undefined;
+    return `testcase/frontend/evidence/${caseId}`;
+}