rea-agents 6.3.0 → 6.5.0

package/dist/domain/binaryTarget.js

@@ -1,22 +1,26 @@
 import { err, ok } from "./result.js";
-import { mzWindowsHeaderOffset, parseDosMzHeader } from "./dosMz.js";
+import { readElfFixedHeader } from "./elfFixedHeader.js";
+import { observeMzWindowsHeader, parseDosMzHeader } from "./dosMz.js";
+import { decodePeMachine } from "./peMachine.js";
+import { classifyFatContainerIdentity, readFatContainerHeader, } from "./apple/machoContainer.js";
 /**
  * Parse supported executable headers without I/O. The caller supplies the host
  * architecture used for deterministic FAT Mach-O slice selection.
  */
-export const parseExecutableHeader = (bytes, hostArchitecture, fileSize = bytes.length) => {
+export const parseExecutableHeader = (bytes, hostArchitecture, fileSize = bytes.length, mzWindowsHeaderSignature) => {
     if (bytes.length >= 4 &&
         bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
         return parseElf(bytes, fileSize);
     if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a)
-        return parseMz(bytes, fileSize);
+        return parseMz(bytes, fileSize, mzWindowsHeaderSignature);
     if (bytes.length < 8)
         return err("truncated or unsupported binary header");
     const magic = bytes.readUInt32BE(0);
     if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
         return parseThinMachO(bytes, magic, fileSize);
-    if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
-        return parseFatMachO(bytes, magic, hostArchitecture, fileSize);
+    const fatHeader = readFatContainerHeader(bytes, fileSize);
+    if (fatHeader.state !== "not-fat")
+        return parseFatMachO(bytes, hostArchitecture, fatHeader);
     return err("unsupported binary format");
 };
 const parseThinMachO = (bytes, magic, fileSize) => {
@@ -38,88 +42,136 @@ const parseThinMachO = (bytes, magic, fileSize) => {
         availableArchitectures: [architecture],
     });
 };
-const parseFatMachO = (bytes, magic, host, fileSize) => {
-    const little = magic === 0xbebafeca || magic === 0xbfbafeca;
-    const is64 = magic === 0xcafebabf || magic === 0xbfbafeca;
-    if (bytes.length < 8)
-        return err("truncated FAT header");
-    const read = (offset) => little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
-    const count = read(4);
-    const entrySize = is64 ? 32 : 20;
-    if (count === 0 || count > 128 || bytes.length < 8 + count * entrySize)
+const parseFatMachO = (bytes, host, header) => {
+    if (header.state === "needs-data")
         return err("truncated or invalid FAT architecture table");
+    if (header.state === "malformed")
+        return err(header.reason);
+    const identityError = fatIdentityError(bytes, header);
+    if (identityError !== null)
+        return err(identityError);
     const architectures = [];
-    const sliceEnds = new Map();
-    for (let index = 0; index < count; index += 1) {
-        const entry = 8 + index * entrySize;
-        const architecture = machArchitecture(read(entry));
+    const slices = new Map();
+    for (const declaration of header.slices) {
+        const architecture = machArchitecture(declaration.cpuType);
         if (architecture === undefined || architectures.includes(architecture))
             continue;
         architectures.push(architecture);
-        const offset = is64
-            ? little
-                ? bytes.readBigUInt64LE(entry + 8)
-                : bytes.readBigUInt64BE(entry + 8)
-            : BigInt(read(entry + 8));
-        const size = is64
-            ? little
-                ? bytes.readBigUInt64LE(entry + 16)
-                : bytes.readBigUInt64BE(entry + 16)
-            : BigInt(read(entry + 12));
-        sliceEnds.set(architecture, offset + size);
+        slices.set(architecture, {
+            offset: declaration.offset,
+            size: declaration.size,
+        });
     }
-    const preferred = host === "arm64"
-        ? "arm64"
-        : host === "x64"
-            ? "x86_64"
-            : host === "ia32"
-                ? "x86"
-                : host === "arm"
-                    ? "arm"
-                    : undefined;
-    if (preferred === undefined || !architectures.includes(preferred))
+    const preferred = fatHostArchitecture(host);
+    const slice = preferred === undefined ? undefined : slices.get(preferred);
+    if (preferred === undefined || slice === undefined)
         return err(`FAT binary has no host-compatible ${host} architecture`);
-    const sliceEnd = sliceEnds.get(preferred) ?? 0n;
-    if (sliceEnd > BigInt(fileSize))
-        return err(`truncated FAT slice: the ${preferred} slice ends at byte ${sliceEnd}; the file has ${fileSize}`);
+    const minimumHeaderSize = preferred === "arm64" || preferred === "x86_64" ? 32 : 28;
+    if (slice.size < minimumHeaderSize)
+        return err(`FAT slice for ${preferred} is shorter than its Mach-O header`);
     return ok({
-        format: "mach-o",
+        format: "mach-o-universal",
         architecture: preferred,
         availableArchitectures: architectures,
+        universalSlice: { offset: slice.offset, size: slice.size },
+    });
+};
+const fatHostArchitecture = (host) => {
+    switch (host) {
+        case "arm64":
+            return "arm64";
+        case "x64":
+            return "x86_64";
+        case "ia32":
+            return "x86";
+        case "arm":
+            return "arm";
+        default:
+            return undefined;
+    }
+};
+const fatIdentityError = (bytes, header) => {
+    const identity = classifyFatContainerIdentity(header, (offset) => {
+        if (offset >= bytes.length)
+            return undefined;
+        if (offset + 4 > bytes.length)
+            return null;
+        return bytes.readUInt32BE(offset);
     });
+    if (identity.state === "needs-slice-header")
+        return "FAT slice identity is outside the bounded prefix";
+    if (identity.state === "not-mach-o")
+        return "FAT table does not identify a Mach-O image";
+    if (identity.state === "malformed")
+        return identity.reason;
+    return null;
 };
 const parseElf = (bytes, fileSize) => {
-    if (bytes.length < 6)
-        return err("truncated ELF header");
-    if (bytes[4] !== 1 && bytes[4] !== 2)
-        return err("unsupported ELF class");
-    const little = bytes[5] === 1;
-    if (!little && bytes[5] !== 2)
-        return err("unsupported ELF endianness");
-    const headerSize = bytes[4] === 1 ? 52 : 64;
-    if (bytes.length < headerSize)
-        return err(`truncated ELF header: an ELF${bytes[4] === 1 ? 32 : 64} header needs ${headerSize} bytes; the file has ${fileSize}`);
+    const fixedHeader = readElfFixedHeader(bytes, fileSize);
+    if (!fixedHeader.ok)
+        return fixedHeader;
+    const { elfClass, byteOrder } = fixedHeader.value;
+    const little = byteOrder === "little";
     const machine = little ? bytes.readUInt16LE(18) : bytes.readUInt16BE(18);
     const architecture = elfArchitecture(machine);
     if (architecture === undefined)
         return err("unsupported ELF architecture");
+    if (architecture === "mips" ||
+        architecture === "riscv" ||
+        architecture === "powerpc") {
+        const flagsOffset = elfClass === 32 ? 36 : 48;
+        const metadata = {
+            elfClass,
+            byteOrder: little ? "little" : "big",
+            type: little ? bytes.readUInt16LE(16) : bytes.readUInt16BE(16),
+            flags: little
+                ? bytes.readUInt32LE(flagsOffset)
+                : bytes.readUInt32BE(flagsOffset),
+        };
+        if (architecture === "powerpc")
+            return ok({
+                format: "elf",
+                architecture,
+                availableArchitectures: [architecture],
+                powerpc: metadata,
+            });
+        return architecture === "mips"
+            ? ok({
+                format: "elf",
+                architecture,
+                availableArchitectures: [architecture],
+                mips: metadata,
+            })
+            : ok({
+                format: "elf",
+                architecture,
+                availableArchitectures: [architecture],
+                riscv: metadata,
+            });
+    }
     return ok({
         format: "elf",
         architecture,
         availableArchitectures: [architecture],
     });
 };
-const parseMz = (bytes, fileSize) => {
-    const offset = mzWindowsHeaderOffset(bytes);
-    if (offset !== null) {
+const parseMz = (bytes, fileSize, signatureAtOffset) => {
+    const windowsHeader = observeMzWindowsHeader(bytes, fileSize, signatureAtOffset);
+    if (windowsHeader.state === "header-needed" ||
+        windowsHeader.state === "signature-needed")
+        return err("Windows new-header pointer or signature is outside the bounded prefix");
+    if (windowsHeader.state === "declared") {
+        const { offset } = windowsHeader;
         if (offset < 64 || offset > bytes.length - 24)
             return err("invalid or truncated Windows executable header in MZ image");
-        const signature = bytes.toString("ascii", offset, offset + 2);
-        if (["NE", "LE", "LX"].includes(signature))
-            return err(`unsupported ${signature} executable in MZ image`);
-        return parsePeRecord(bytes.subarray(offset));
+        if (["NE", "LE", "LX"].includes(windowsHeader.signature))
+            return err(`unsupported ${windowsHeader.signature} executable in MZ image`);
+        if (windowsHeader.signature !== "PE")
+            return err("invalid or truncated Windows executable header in MZ image");
+        const codeView = parsePeCodeViewFromBuffer(bytes, offset);
+        return parsePeRecord(bytes.subarray(offset), codeView);
     }
-    const parsed = parseDosMzHeader(bytes, fileSize);
+    const parsed = parseDosMzHeader(bytes, fileSize, signatureAtOffset);
     return parsed.ok
         ? ok({
             format: "dos-mz",
@@ -129,13 +181,15 @@ const parseMz = (bytes, fileSize) => {
         : parsed;
 };
 /** Parse a bounded PE signature, COFF record, and optional header without I/O. */
-export const parsePeRecord = (record) => {
+export const parsePeRecord = (record, codeView) => {
     if (record.length < 24 ||
         record.toString("binary", 0, 4) !== "PE\u0000\u0000")
         return err("invalid or truncated PE header");
-    const architecture = peArchitecture(record.readUInt16LE(4));
-    if (architecture === undefined)
-        return err("unsupported PE architecture");
+    const machineType = record.readUInt16LE(4);
+    const machine = decodePeMachine(machineType);
+    if (machine === undefined)
+        return err(`unsupported PE architecture (COFF machine 0x${machineType.toString(16).padStart(4, "0")})`);
+    const { architecture } = machine;
     const optionalHeaderSize = record.readUInt16LE(20);
     if (optionalHeaderSize > 4096 || record.length < 24 + optionalHeaderSize)
         return err("invalid or truncated PE optional header");
@@ -143,6 +197,8 @@ export const parsePeRecord = (record) => {
     const managed = peManagedStatus(optionalHeader, architecture);
     if (!managed.ok)
         return managed;
+    if (machine.nativeOsOverride && !managed.value)
+        return err("unsupported PE architecture");
     const characteristics = record.readUInt16LE(22);
     return ok({
         format: "pe",
@@ -154,8 +210,134 @@ export const parsePeRecord = (record) => {
                 ? "application"
                 : "shared-library",
         managed: managed.value,
+        ...(codeView !== undefined ? { codeView } : {}),
     });
 };
+/** Parse CodeView record data (RSDS or NB10) from raw data bytes. */
+export const parseCodeViewData = (buffer, sizeOfData) => {
+    if (sizeOfData < 16 || buffer.length < 16)
+        return undefined;
+    const magic = buffer.subarray(0, 4).toString("binary");
+    const pathOffset = magic === "RSDS" ? 24 : magic === "NB10" ? 16 : undefined;
+    if (pathOffset === undefined ||
+        sizeOfData <= pathOffset ||
+        buffer.length <= pathOffset)
+        return undefined;
+    const end = buffer.indexOf(0, pathOffset);
+    if (end <= pathOffset || end >= sizeOfData)
+        return undefined;
+    const pdbPath = buffer.toString("utf8", pathOffset, end);
+    const pdbFileName = pdbPath.split(/[/\\]/u).pop() ?? pdbPath;
+    if (magic === "RSDS" && sizeOfData >= 24 && buffer.length >= 24) {
+        const part1 = buffer.readUInt32LE(4).toString(16).padStart(8, "0");
+        const part2 = buffer.readUInt16LE(8).toString(16).padStart(4, "0");
+        const part3 = buffer.readUInt16LE(10).toString(16).padStart(4, "0");
+        const part4 = buffer.subarray(12, 14).toString("hex");
+        const part5 = buffer.subarray(14, 20).toString("hex");
+        const guid = `${part1}-${part2}-${part3}-${part4}-${part5}`;
+        const age = buffer.readUInt32LE(20);
+        return { pdbPath, pdbFileName, guid, age };
+    }
+    if (magic === "NB10") {
+        const age = buffer.readUInt32LE(12);
+        return { pdbPath, pdbFileName, guid: null, age };
+    }
+    return undefined;
+};
+/** Locate the debug directory RVA and size from a PE optional header. */
+export const peDebugDirectoryEntry = (optionalHeader) => {
+    if (optionalHeader.length < 2)
+        return undefined;
+    const magic = optionalHeader.readUInt16LE(0);
+    if (magic !== 0x10b && magic !== 0x20b)
+        return undefined;
+    const directoryOffset = magic === 0x20b ? 112 : 96;
+    const directoryCountOffset = directoryOffset - 4;
+    if (optionalHeader.length < directoryCountOffset + 4)
+        return undefined;
+    const directoryCount = optionalHeader.readUInt32LE(directoryCountOffset);
+    if (directoryCount <= 6)
+        return undefined;
+    const debugEntryOffset = directoryOffset + 6 * 8;
+    if (optionalHeader.length < debugEntryOffset + 8)
+        return undefined;
+    const debugRva = optionalHeader.readUInt32LE(debugEntryOffset);
+    const debugSize = optionalHeader.readUInt32LE(debugEntryOffset + 4);
+    if (debugRva === 0 || debugSize < 28)
+        return undefined;
+    return {
+        debugRva,
+        debugSize,
+        sizeOfHeaders: optionalHeader.readUInt32LE(60),
+    };
+};
+/** Translate an RVA to an absolute file offset using the PE section table. */
+export const peRvaToFileOffset = (rva, sectionTable, numberOfSections, sizeOfHeaders, size = 1) => {
+    if (rva < sizeOfHeaders && size <= sizeOfHeaders - rva)
+        return rva;
+    for (let i = 0; i < numberOfSections; i++) {
+        const offset = i * 40;
+        if (sectionTable.length < offset + 40)
+            break;
+        const virtualAddress = sectionTable.readUInt32LE(offset + 12);
+        const sizeOfRawData = sectionTable.readUInt32LE(offset + 16);
+        const pointerToRawData = sectionTable.readUInt32LE(offset + 20);
+        if (pointerToRawData > 0 &&
+            rva >= virtualAddress &&
+            rva - virtualAddress < sizeOfRawData &&
+            size <= sizeOfRawData - (rva - virtualAddress)) {
+            return pointerToRawData + (rva - virtualAddress);
+        }
+    }
+    return undefined;
+};
+/** Parse CodeView metadata from a bounded in-memory PE image buffer. */
+export const parsePeCodeViewFromBuffer = (fileBytes, peOffset) => {
+    if (fileBytes.length < peOffset + 24)
+        return undefined;
+    const numberOfSections = fileBytes.readUInt16LE(peOffset + 6);
+    const optionalHeaderSize = fileBytes.readUInt16LE(peOffset + 20);
+    if (optionalHeaderSize > 4096 ||
+        fileBytes.length < peOffset + 24 + optionalHeaderSize)
+        return undefined;
+    const optionalHeader = fileBytes.subarray(peOffset + 24, peOffset + 24 + optionalHeaderSize);
+    const debugDir = peDebugDirectoryEntry(optionalHeader);
+    if (debugDir === undefined)
+        return undefined;
+    const sectionTableOffset = peOffset + 24 + optionalHeaderSize;
+    const sectionTableSize = numberOfSections * 40;
+    if (fileBytes.length < sectionTableOffset + sectionTableSize)
+        return undefined;
+    const sectionTable = fileBytes.subarray(sectionTableOffset, sectionTableOffset + sectionTableSize);
+    const debugFileOffset = peRvaToFileOffset(debugDir.debugRva, sectionTable, numberOfSections, debugDir.sizeOfHeaders, Math.min(debugDir.debugSize, 4096));
+    if (debugFileOffset === undefined || fileBytes.length < debugFileOffset + 28)
+        return undefined;
+    const maxDebugBytes = Math.min(debugDir.debugSize, fileBytes.length - debugFileOffset);
+    const numEntries = Math.floor(maxDebugBytes / 28);
+    for (let j = 0; j < numEntries; j++) {
+        const entryOffset = debugFileOffset + j * 28;
+        const type = fileBytes.readUInt32LE(entryOffset + 12);
+        if (type !== 2)
+            continue; // IMAGE_DEBUG_TYPE_CODEVIEW
+        const sizeOfData = fileBytes.readUInt32LE(entryOffset + 16);
+        let pointerToRawData = fileBytes.readUInt32LE(entryOffset + 24);
+        if (pointerToRawData === 0) {
+            const addressOfRawData = fileBytes.readUInt32LE(entryOffset + 20);
+            const mapped = peRvaToFileOffset(addressOfRawData, sectionTable, numberOfSections, debugDir.sizeOfHeaders, Math.min(sizeOfData, 4096));
+            if (mapped === undefined)
+                continue;
+            pointerToRawData = mapped;
+        }
+        if (sizeOfData < 16 ||
+            fileBytes.length < pointerToRawData + Math.min(sizeOfData, 24))
+            continue;
+        const codeViewData = fileBytes.subarray(pointerToRawData, Math.min(fileBytes.length, pointerToRawData + sizeOfData));
+        const parsed = parseCodeViewData(codeViewData, sizeOfData);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return undefined;
+};
 const peManagedStatus = (optionalHeader, architecture) => {
     if (optionalHeader.length < 2)
         return err("truncated PE optional header");
@@ -197,25 +379,16 @@ const elfArchitecture = (machine) => {
             return "x86";
         case 62:
             return "x86_64";
+        case 8: // EM_MIPS: ISA, ABI and byte order remain separate ELF facts.
+            return "mips";
+        case 20: // EM_PPC; byte order and processor variant remain ELF declarations.
+            return "powerpc";
         case 40:
             return "arm";
         case 183:
             return "arm64";
-    }
-    return undefined;
-};
-const peArchitecture = (machine) => {
-    switch (machine) {
-        case 0x14c:
-            return "x86";
-        case 0x8664:
-            return "x86_64";
-        case 0x1c0:
-        case 0x1c2:
-        case 0x1c4:
-            return "arm";
-        case 0xaa64:
-            return "arm64";
+        case 243: // EM_RISCV: XLEN, byte order and e_flags remain separate ELF facts.
+            return "riscv";
     }
     return undefined;
 };

package/dist/domain/binaryTargetTypes.js

@@ -1 +1,21 @@
-export {};
+/** Provider-neutral CPU families detected from headers or explicitly selected raw loads. */
+export const BINARY_ARCHITECTURES = [
+    "x86",
+    "x86_64",
+    "arm",
+    "arm64",
+    "mips",
+    "6502",
+    "riscv",
+    "powerpc",
+];
+/** Families whose parsed target variant carries `ElfFamilyMetadata`. */
+export const ELF_METADATA_ARCHITECTURES = [
+    "mips",
+    "riscv",
+    "powerpc",
+];
+/** Families whose ISA and ABI need a separate ELF declaration to be admitted. */
+export const isElfMetadataArchitecture = (architecture) => ELF_METADATA_ARCHITECTURES.includes(architecture);
+/** Whether an executable target contains a thin or universal Mach-O image. */
+export const isMachOFormat = (format) => format === "mach-o" || format === "mach-o-universal";

package/dist/domain/browserNetworkEvidence.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
+export const PLAYWRIGHT_RESPONSE_BODY_PROVENANCE_LIMITATION = "Captured response-body bytes are the result of Playwright's Response.body() API. Playwright may satisfy that API with a credentialed follow-up load of the request URL when CDP has no body, so transaction and event links do not verify that retained bytes came from the original network transaction.";
 /** Resolved network content selection recorded by a capture. */
 export const browserNetworkContentSelectionValuesSchema = z.strictObject({
     request_body: z.boolean(),
@@ -39,6 +40,9 @@ export const browserNetworkBodySchema = z.union([
         state: z.literal("captured"),
         representation: z.enum([
             "browser-exposed-request-bytes",
+            "playwright-response-body-bytes",
+            // Retained for captures produced before response-body provenance was
+            // narrowed to the bytes Playwright exposes through Response.body().
             "browser-decoded-response-bytes",
         ]),
         encoding: z.literal("base64"),

package/dist/domain/browserObservation.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { urlDeclaresQueryOrFragment } from "./urlComponents.js";
+import { parseUrlQueryParameterNames } from "./recordedTransportUrl.js";
 const parseExactOrigin = (value) => {
     let url;
     try {
@@ -14,8 +16,7 @@ const parseExactOrigin = (value) => {
         url.username !== "" ||
         url.password !== "" ||
         url.pathname !== "/" ||
-        url.search !== "" ||
-        url.hash !== "")
+        urlDeclaresQueryOrFragment(url))
         return undefined;
     return url.origin;
 };
@@ -36,43 +37,97 @@ export const browserOriginSchema = z
 });
 /** Recognize the URL API's bracketed IPv6 form and normalized bare literals. */
 export const isLiteralLoopbackHostname = (hostname) => hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+const HTTP_ENDPOINT_MESSAGE = "CDP endpoint must be an explicit-port HTTP URL on 127.0.0.1 or ::1";
+const BROWSER_SOCKET_PATH = "/devtools/browser/";
+const REDACTED_BROWSER_SOCKET_PATH = `${BROWSER_SOCKET_PATH}[REDACTED]`;
+/** Normalized origin of an accepted loopback CDP HTTP discovery endpoint. */
+const httpDiscoveryOrigin = (url) => url.protocol === "http:" &&
+    isLiteralLoopbackHostname(url.hostname) &&
+    url.port !== "" &&
+    url.username === "" &&
+    url.password === "" &&
+    url.pathname === "/" &&
+    !urlDeclaresQueryOrFragment(url)
+    ? url.origin
+    : undefined;
+/** Scheme and authority of an accepted loopback CDP browser WebSocket. */
+const browserSocketAuthority = (url) => {
+    const id = url.pathname.slice(BROWSER_SOCKET_PATH.length);
+    return url.protocol === "ws:" &&
+        isLiteralLoopbackHostname(url.hostname) &&
+        url.port !== "" &&
+        url.username === "" &&
+        url.password === "" &&
+        !urlDeclaresQueryOrFragment(url) &&
+        url.pathname.startsWith(BROWSER_SOCKET_PATH) &&
+        id.length > 0 &&
+        !id.includes("/")
+        ? `${url.protocol}//${url.host}`
+        : undefined;
+};
 /** Loopback-only HTTP endpoint accepted for a user-owned CDP browser. */
 export const browserEndpointSchema = z
     .string()
     .min(1)
     .transform((value, context) => {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch (cause) {
-        // Invalid input is reported through the zod issue.
-        void cause;
+    const url = URL.parse(value);
+    const origin = url === null ? undefined : httpDiscoveryOrigin(url);
+    if (origin !== undefined)
+        return origin;
+    context.addIssue({
+        code: "custom",
+        message: url === null ? "Invalid CDP endpoint URL" : HTTP_ENDPOINT_MESSAGE,
+    });
+    return z.NEVER;
+});
+/** Loopback CDP HTTP discovery origin or browser WebSocket URL. */
+export const browserObservationEndpointSchema = z
+    .string()
+    .min(1)
+    .describe("Literal loopback CDP endpoint: http://127.0.0.1:PORT, or ws://127.0.0.1:PORT/devtools/browser/ID.")
+    .transform((value, context) => {
+    const url = URL.parse(value);
+    if (url === null) {
         context.addIssue({ code: "custom", message: "Invalid CDP endpoint URL" });
         return z.NEVER;
     }
-    if (url.protocol !== "http:" ||
-        !isLiteralLoopbackHostname(url.hostname) ||
-        url.port === "" ||
-        url.username !== "" ||
-        url.password !== "" ||
-        url.pathname !== "/" ||
-        url.search !== "" ||
-        url.hash !== "") {
-        context.addIssue({
-            code: "custom",
-            message: "CDP endpoint must be an explicit-port HTTP URL on 127.0.0.1 or ::1",
-        });
-        return z.NEVER;
-    }
-    return url.origin;
+    const origin = httpDiscoveryOrigin(url);
+    if (origin !== undefined)
+        return { transport: "http_discovery", url: origin, recorded: origin };
+    const authority = browserSocketAuthority(url);
+    if (authority !== undefined)
+        return {
+            transport: "browser_websocket",
+            url: url.href,
+            recorded: `${authority}${REDACTED_BROWSER_SOCKET_PATH}`,
+        };
+    context.addIssue({
+        code: "custom",
+        message: url.protocol === "ws:"
+            ? "CDP browser WebSocket must be ws://127.0.0.1:PORT/devtools/browser/ID or ws://[::1]:PORT/devtools/browser/ID"
+            : HTTP_ENDPOINT_MESSAGE,
+    });
+    return z.NEVER;
+});
+/** Evidence form of a passive browser endpoint, with any socket identifier redacted. */
+export const recordedBrowserObservationEndpointSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    const url = URL.parse(value);
+    return (url !== null &&
+        (httpDiscoveryOrigin(url) !== undefined ||
+            (browserSocketAuthority(url) !== undefined &&
+                url.pathname === REDACTED_BROWSER_SOCKET_PATH)));
+}, {
+    message: "Recorded CDP endpoint must be a loopback HTTP origin or a redacted browser WebSocket URL",
 });
 export const browserAllowedOriginsSchema = z
     .array(browserOriginSchema)
     .transform((origins) => Array.from(new Set(origins)).sort())
     .default([]);
 const browserInput = {
-    cdp_endpoint: browserEndpointSchema,
+    cdp_endpoint: browserObservationEndpointSchema,
     allowed_origins: browserAllowedOriginsSchema,
 };
 /** Public input for complete discovery, optionally filtered by exact origin. */
@@ -92,7 +147,7 @@ const inspectWebPageInputFacts = {
 };
 const inspectWebPageWithoutSourceSchema = z.strictObject({
     ...inspectWebPageInputFacts,
-    include_script_sources: z.literal(false).default(false),
+    include_script_sources: z.literal(false).optional().default(false),
 });
 const inspectWebPageWithSourceShapeSchema = z.strictObject({
     ...inspectWebPageInputFacts,
@@ -109,9 +164,13 @@ const refineInspectWebPageInput = (input, context) => {
 /** Caller schema for source-capturing inspection and bundle analysis. */
 export const inspectWebPageWithSourceInputSchema = inspectWebPageWithSourceShapeSchema.superRefine(refineInspectWebPageInput);
 /** Caller-visible schema for one passive inspection. */
-export const inspectWebPageInputSchema = z.union([
+export const inspectWebPageInputSchema = z.discriminatedUnion("include_script_sources", [
     inspectWebPageWithoutSourceSchema.superRefine(refineInspectWebPageInput),
-    inspectWebPageWithSourceInputSchema,
+    inspectWebPageWithSourceShapeSchema
+        .extend({
+        include_script_sources: z.literal(true),
+    })
+        .superRefine(refineInspectWebPageInput),
 ]);
 export const sanitizedBrowserUrlSchema = z.object({
     url: z.string(),
@@ -136,7 +195,7 @@ export const sanitizeBrowserUrl = (value) => {
         };
     }
     const hadCredentials = parsed.username !== "" || parsed.password !== "";
-    const names = [...parsed.searchParams.keys()];
+    const names = [...parseUrlQueryParameterNames(parsed.search)];
     const sanitizedUrl = hadCredentials
         ? removeUrlUserInfo(value, parsed)
         : value;