rea-agents 6.3.0 → 6.5.0

package/dist/browser/BrowserScenarioSecrets.js

@@ -2,15 +2,150 @@ import { createHash } from "node:crypto";
 import { sanitizeBrowserUrl, } from "../domain/browserObservation.js";
 const REDACTION_PREFIX = "[REDACTED:";
 const encodedSecretValues = (secret) => new Set([
-    secret,
     encodeURIComponent(secret),
     new URLSearchParams([["value", secret]]).toString().slice("value=".length),
 ]);
+const normalizePercentEscapes = (value) => {
+    if (!value.includes("%"))
+        return value;
+    return value.replace(/%[0-9a-f]{2}/giu, (escape) => escape.toLowerCase());
+};
+const secretPatterns = (secret, spellings) => {
+    if (secret === "")
+        return [];
+    const patterns = [
+        { text: secret, searchText: secret, percentInsensitive: false },
+        ...[...encodedSecretValues(secret)].map((text) => ({
+            text,
+            searchText: normalizePercentEscapes(text),
+            percentInsensitive: true,
+        })),
+    ];
+    if (spellings === "text")
+        patterns.push({
+            text: JSON.stringify(secret).slice(1, -1),
+            searchText: JSON.stringify(secret).slice(1, -1),
+            percentInsensitive: false,
+        });
+    const seen = new Set();
+    return patterns.filter(({ text, percentInsensitive }) => {
+        if (text === "")
+            return false;
+        const key = `${percentInsensitive ? "percent" : "literal"}:${text}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+const declaredPatterns = (values, spellings) => {
+    const seen = new Set();
+    return [...values.values()]
+        .flatMap((secret) => secretPatterns(secret, spellings))
+        .filter(({ text, percentInsensitive }) => {
+        const key = `${percentInsensitive ? "percent" : "literal"}:${text}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+const secretReplacements = (values, spellings) => [...values]
+    .flatMap(([id, secret]) => secretPatterns(secret, spellings).map((pattern) => ({ id, ...pattern })))
+    .sort((left, right) => right.text.length - left.text.length ||
+    (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+const normalizePercentEscapesBytes = (value) => {
+    if (value.indexOf(37) < 0)
+        return value;
+    const normalized = Buffer.from(value);
+    for (let index = 0; index + 2 < normalized.length; index += 1)
+        if (normalized[index] === 37 &&
+            isHexByte(normalized[index + 1]) &&
+            isHexByte(normalized[index + 2])) {
+            normalized[index + 1] = lowercaseHexByte(normalized[index + 1]);
+            normalized[index + 2] = lowercaseHexByte(normalized[index + 2]);
+            index += 2;
+        }
+    return normalized;
+};
+const isHexByte = (value) => value !== undefined &&
+    ((value >= 48 && value <= 57) ||
+        (value >= 65 && value <= 70) ||
+        (value >= 97 && value <= 102));
+const lowercaseHexByte = (value) => value >= 65 && value <= 70 ? value + 32 : value;
+const patternMatches = (value, normalizedValue, pattern) => (pattern.percentInsensitive ? normalizedValue : value).includes(pattern.searchText);
+const containsSecretPattern = (value, normalizedValue, patterns) => {
+    if (patterns.length === 0)
+        return false;
+    return patterns.some((pattern) => patternMatches(value, normalizedValue, pattern));
+};
+const containsSecretBytePattern = (value, normalizedValue, needles) => needles.some((needle) => (needle.percentInsensitive ? normalizedValue : value).includes(needle.needle));
+/** Pick a marker that does not itself contain a declared secret spelling. */
+const redactionMarker = (id, patterns) => {
+    const candidates = [`${REDACTION_PREFIX}${id}]`, "[REDACTED]", "…", ""];
+    return (candidates.find((candidate) => patterns.every((pattern) => !patternMatches(candidate, normalizePercentEscapes(candidate), pattern))) ?? "");
+};
+const replaceSecretLiterals = (value, replacements, patterns) => {
+    const normalizedValue = replacements.some(({ percentInsensitive }) => percentInsensitive)
+        ? normalizePercentEscapes(value)
+        : value;
+    const parts = [];
+    let offset = 0;
+    while (offset < value.length) {
+        let next;
+        for (const replacement of replacements) {
+            const search = replacement.searchText;
+            const view = replacement.percentInsensitive ? normalizedValue : value;
+            const index = view.indexOf(search, offset);
+            if (index >= 0 &&
+                (next === undefined ||
+                    index < next.index ||
+                    (index === next.index && replacement.text.length > next.text.length)))
+                next = { ...replacement, index };
+        }
+        if (next === undefined)
+            break;
+        const marker = redactionMarker(next.id, patterns);
+        parts.push(value.slice(offset, next.index), marker);
+        offset = next.index + next.text.length;
+    }
+    if (parts.length === 0)
+        return value;
+    parts.push(value.slice(offset));
+    return parts.join("");
+};
+const secretNeedles = (replacements, patterns) => replacements.map((pattern) => ({
+    id: pattern.id,
+    needle: Buffer.from(pattern.searchText),
+    percentInsensitive: pattern.percentInsensitive,
+    marker: Buffer.from(redactionMarker(pattern.id, patterns)),
+}));
 /** Resolved secret values kept only for one in-memory scenario session. */
 export class BrowserScenarioSecrets {
     values;
+    urlPatterns;
+    textPatterns;
+    urlReplacements;
+    textReplacements;
+    textNeedles;
+    redactionCostPerCharacter;
     constructor(values) {
         this.values = values;
+        this.urlPatterns = declaredPatterns(values, "url");
+        this.textPatterns = declaredPatterns(values, "text");
+        this.urlReplacements = secretReplacements(values, "url");
+        this.textReplacements = secretReplacements(values, "text");
+        this.textNeedles = secretNeedles(this.textReplacements, this.textPatterns);
+        this.redactionCostPerCharacter = 8;
+        for (const [replacements, patterns] of [
+            [this.textReplacements, this.textPatterns],
+            [this.urlReplacements, this.urlPatterns],
+        ])
+            for (const replacement of replacements)
+                this.redactionCostPerCharacter = Math.max(this.redactionCostPerCharacter, 8 +
+                    (Buffer.byteLength(redactionMarker(replacement.id, patterns)) * 8 +
+                        128) /
+                        replacement.text.length);
     }
     static resolve(scenario, environment) {
         const values = new Map();
@@ -37,47 +172,51 @@ export class BrowserScenarioSecrets {
             url.searchParams.append(name, this.value(value));
         return url.href;
     }
+    /** Conservative preflight for output expansion and per-match part arrays.
+     * Callers measuring untrusted observations must reserve this cost before
+     * invoking redaction. A one-byte secret can otherwise expand every byte.
+     */
+    redactionAllocationCost(length) {
+        return Math.ceil(length * this.redactionCostPerCharacter);
+    }
     redact(value) {
-        let output = value;
-        const replacements = [...this.values].sort(([leftId, left], [rightId, right]) => right.length - left.length ||
-            (leftId < rightId ? -1 : leftId > rightId ? 1 : 0));
-        for (const [id, secret] of replacements)
-            if (secret !== "")
-                output = output.replaceAll(secret, `${REDACTION_PREFIX}${id}]`);
-        return output;
+        const patterns = this.textPatterns;
+        if (patterns.length === 0)
+            return value;
+        const output = replaceSecretLiterals(value, this.textReplacements, patterns);
+        return containsSecretPattern(output, normalizePercentEscapes(output), patterns)
+            ? ""
+            : output;
     }
-    /** Replace declared UTF-8, URI/form, and JSON-escaped secrets without decoding binary data. */
+    /** Replace declared UTF-8, URI/form, and JSON-escaped secret spellings. */
     redactBytes(value) {
-        const candidates = [...this.values]
-            .flatMap(([id, secret]) => {
-            if (secret === "")
-                return [];
-            return [
-                ...new Set([
-                    ...encodedSecretValues(secret),
-                    JSON.stringify(secret).slice(1, -1),
-                ]),
-            ].map((text) => {
-                const needle = Buffer.from(text);
-                return {
-                    id,
-                    needle,
-                    marker: Buffer.from(`${REDACTION_PREFIX}${id}]`),
-                    index: value.indexOf(needle),
-                };
-            });
-        })
+        const patterns = this.textPatterns;
+        if (patterns.length === 0)
+            return value;
+        const candidates = this.textNeedles;
+        const hasPercentPatterns = candidates.some(({ percentInsensitive }) => percentInsensitive);
+        const normalizedValue = hasPercentPatterns && value.indexOf(37) >= 0
+            ? normalizePercentEscapesBytes(value)
+            : value;
+        const sortedCandidates = candidates
+            .map((candidate) => ({
+            ...candidate,
+            index: (candidate.percentInsensitive ? normalizedValue : value).indexOf(candidate.needle),
+        }))
             .sort((left, right) => right.needle.length - left.needle.length ||
             (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
         const parts = [];
         let offset = 0;
         while (true) {
             let next;
-            for (const candidate of candidates) {
+            for (const candidate of sortedCandidates) {
                 if (candidate.index >= 0 && candidate.index < offset)
-                    candidate.index = value.indexOf(candidate.needle, offset);
+                    candidate.index = (candidate.percentInsensitive ? normalizedValue : value).indexOf(candidate.needle, offset);
                 if (candidate.index >= 0 &&
-                    (next === undefined || candidate.index < next.index))
+                    (next === undefined ||
+                        candidate.index < next.index ||
+                        (candidate.index === next.index &&
+                            candidate.needle.length > next.needle.length)))
                     next = candidate;
             }
             if (next === undefined)
@@ -88,20 +227,27 @@ export class BrowserScenarioSecrets {
         if (parts.length === 0)
             return value;
         parts.push(value.subarray(offset));
-        return Buffer.concat(parts);
+        const redacted = Buffer.concat(parts);
+        const normalizedRedacted = hasPercentPatterns && redacted.indexOf(37) >= 0
+            ? normalizePercentEscapesBytes(redacted)
+            : redacted;
+        return containsSecretBytePattern(redacted, normalizedRedacted, candidates)
+            ? Buffer.alloc(0)
+            : redacted;
     }
     /** Remove only declared secret values from one URL and report that action. */
     sanitizeUrl(value) {
-        let output = value;
-        const replacements = [...this.values].sort(([leftId, left], [rightId, right]) => right.length - left.length ||
-            (leftId < rightId ? -1 : leftId > rightId ? 1 : 0));
-        for (const [id, secret] of replacements) {
-            if (secret === "")
-                continue;
-            const marker = `${REDACTION_PREFIX}${id}]`;
-            for (const candidate of encodedSecretValues(secret))
-                output = output.replaceAll(candidate, marker);
-        }
+        const patterns = this.urlPatterns;
+        if (patterns.length === 0)
+            return sanitizeBrowserUrl(value);
+        const output = replaceSecretLiterals(value, this.urlReplacements, patterns);
+        if (containsSecretPattern(output, normalizePercentEscapes(output), patterns))
+            return {
+                url: "",
+                origin: null,
+                query_parameter_names: [],
+                redacted: true,
+            };
         const sanitized = sanitizeBrowserUrl(output);
         return {
             ...sanitized,
@@ -109,14 +255,13 @@ export class BrowserScenarioSecrets {
         };
     }
     fingerprint(value) {
-        for (const secret of this.values.values())
-            if (secret !== "" && value.includes(secret))
-                return { value_state: "redacted-secret", value_sha256: null };
+        const patterns = this.textPatterns;
+        if (patterns.length > 0 &&
+            containsSecretPattern(value, normalizePercentEscapes(value), patterns))
+            return { value_state: "redacted-secret", value_sha256: null };
         return {
             value_state: "hashed",
-            value_sha256: createHash("sha256")
-                .update(this.redact(value))
-                .digest("hex"),
+            value_sha256: createHash("sha256").update(value).digest("hex"),
         };
     }
 }

package/dist/browser/CdpBrowserProvider.js

@@ -7,12 +7,12 @@ import { webMcpDiscoverySchema, } from "../domain/webMcpDiscovery.js";
 import { browserCaptureComparisonSchema, compareBrowserCaptures, } from "../domain/browserCaptureComparison.js";
 import { webScreenshotDiffSchema, webScreenshotSchema, } from "../domain/webScreenshot.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
-import {} from "../domain/browserObservationErrors.js";
 import { err, ok } from "../domain/result.js";
-import { discoverCdpEndpoint, hasCdpTargetWebSocket, } from "./CdpEndpoint.js";
-import { closeCdpTargetSession, openCdpTargetSession, } from "./CdpTargetSession.js";
+import { hasCdpTargetWebSocket, } from "./CdpEndpoint.js";
+import { attachCdpTargetSession, closeCdpTargetSession, openCdpEndpoint, openCdpTargetSession, } from "./CdpTargetSession.js";
 import { capturePage } from "./CdpPageCapture.js";
 import { fetchWebSourceMaps } from "./WebSourceMapFetcher.js";
 import { authorizeCdpTarget } from "./CdpAuthorizedTarget.js";
@@ -21,6 +21,7 @@ import { discoverWebMcp } from "./CdpWebMcpDiscovery.js";
 import { captureCdpScreenshot } from "./CdpScreenshot.js";
 import { comparePngScreenshots } from "./PngVisualDiff.js";
 import { CDP_BROWSER_PROVIDER_IDENTITY } from "./providerIdentities.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 const CLEANUP_DOMAINS = ["Network", "Debugger", "Runtime", "Page"];
 /** Passive browser observation through a selected user-owned CDP endpoint. */
 export class CdpBrowserProvider {
@@ -29,7 +30,9 @@ export class CdpBrowserProvider {
     }
     async listTargets(input, options = {}) {
         try {
-            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, "list_browser_targets", options.signal);
+            const endpoint = await openCdpEndpoint(input.cdp_endpoint, "list_browser_targets", options.signal);
+            await endpoint.connection?.close();
+            const { discovery } = endpoint;
             const selected = selectTargets(discovery, input.allowed_origins.length === 0
                 ? undefined
                 : new Set(input.allowed_origins));
@@ -46,11 +49,16 @@ export class CdpBrowserProvider {
                         : [
                             `${String(selected.unconnectable)} otherwise allowed page target(s) lacked a validated direct CDP WebSocket and were excluded.`,
                         ]),
+                    ...(selected.allowed.some((target) => target.attached === null)
+                        ? [
+                            "CDP discovery omitted attachment state for one or more targets; attached is reported as unknown.",
+                        ]
+                        : []),
                 ],
             }));
         }
         catch (cause) {
-            return err(providerError(cause, "list_browser_targets"));
+            return err(providerError(cause, "list_browser_targets", options.signal));
         }
     }
     async inspectPage(input, options = {}) {
@@ -59,7 +67,7 @@ export class CdpBrowserProvider {
             return ok(webPageInspectionSchema.parse(captured.inspection));
         }
         catch (cause) {
-            return err(providerError(cause, "inspect_web_page"));
+            return err(providerError(cause, "inspect_web_page", options.signal));
         }
     }
     async analyzeBundle(input, options = {}) {
@@ -76,61 +84,28 @@ export class CdpBrowserProvider {
             return ok(webBundleAnalysisSchema.parse(analyzeCapturedWebBundle(captured.inspection, sourceMaps)));
         }
         catch (cause) {
-            return err(providerError(cause, "analyze_web_bundle"));
+            // fetchWebSourceMaps rethrows the exact abort reason. Preserve cancellation
+            // even when a caller supplied an AnalysisError as that reason.
+            if (options.signal?.aborted === true && cause === options.signal.reason) {
+                return err(new AnalysisCancelledError("analyze_web_bundle", { cause }));
+            }
+            return err(providerError(cause, "analyze_web_bundle", options.signal));
         }
     }
     async observeSession(input, options = {}) {
-        let targetSession;
         try {
-            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, "observe_web_session", options.signal);
-            const target = authorizeTarget(discovery, input);
-            const scopedInput = scopeToTargetOrigin(input, target);
-            targetSession = await openCdpTargetSession(discovery, target, "observe_web_session", options.signal);
-            return ok(webObservationSessionSchema.parse(await observeCdpSession({
-                connection: targetSession.connection,
-                sessionId: targetSession.sessionId,
-                discovery,
-                target,
-                input: scopedInput,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
-                ...(options.progress === undefined
-                    ? {}
-                    : { progress: options.progress }),
-            })));
+            return ok(webObservationSessionSchema.parse(await withTargetSession(input, "observe_web_session", options, observeCdpSession)));
         }
         catch (cause) {
-            return err(providerError(cause, "observe_web_session"));
-        }
-        finally {
-            if (targetSession !== undefined)
-                await closeCdpTargetSession(targetSession, CLEANUP_DOMAINS, options.signal);
+            return err(providerError(cause, "observe_web_session", options.signal));
         }
     }
     async discoverWebMcpTools(input, options = {}) {
-        let targetSession;
         try {
-            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, "discover_webmcp_tools", options.signal);
-            const target = authorizeTarget(discovery, input);
-            const scopedInput = scopeToTargetOrigin(input, target);
-            targetSession = await openCdpTargetSession(discovery, target, "discover_webmcp_tools", options.signal);
-            return ok(webMcpDiscoverySchema.parse(await discoverWebMcp({
-                connection: targetSession.connection,
-                sessionId: targetSession.sessionId,
-                discovery,
-                target,
-                input: scopedInput,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
-                ...(options.progress === undefined
-                    ? {}
-                    : { progress: options.progress }),
-            })));
+            return ok(webMcpDiscoverySchema.parse(await withTargetSession(input, "discover_webmcp_tools", options, discoverWebMcp)));
         }
         catch (cause) {
-            return err(providerError(cause, "discover_webmcp_tools"));
-        }
-        finally {
-            if (targetSession !== undefined)
-                await closeCdpTargetSession(targetSession, CLEANUP_DOMAINS, options.signal);
+            return err(providerError(cause, "discover_webmcp_tools", options.signal));
         }
     }
     async compareCaptures(input) {
@@ -142,30 +117,11 @@ export class CdpBrowserProvider {
         }
     }
     async captureScreenshot(input, options = {}) {
-        let targetSession;
         try {
-            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, "capture_web_screenshot", options.signal);
-            const target = authorizeTarget(discovery, input);
-            const scopedInput = scopeToTargetOrigin(input, target);
-            targetSession = await openCdpTargetSession(discovery, target, "capture_web_screenshot", options.signal);
-            return ok(webScreenshotSchema.parse(await captureCdpScreenshot({
-                connection: targetSession.connection,
-                sessionId: targetSession.sessionId,
-                discovery,
-                target,
-                input: scopedInput,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
-                ...(options.progress === undefined
-                    ? {}
-                    : { progress: options.progress }),
-            })));
+            return ok(webScreenshotSchema.parse(await withTargetSession(input, "capture_web_screenshot", options, captureCdpScreenshot)));
         }
         catch (cause) {
-            return err(providerError(cause, "capture_web_screenshot"));
-        }
-        finally {
-            if (targetSession !== undefined)
-                await closeCdpTargetSession(targetSession, CLEANUP_DOMAINS, options.signal);
+            return err(providerError(cause, "capture_web_screenshot", options.signal));
         }
     }
     async compareScreenshots(input) {
@@ -173,35 +129,53 @@ export class CdpBrowserProvider {
             return ok(webScreenshotDiffSchema.parse(comparePngScreenshots(input)));
         }
         catch (cause) {
+            if (cause instanceof TypeError)
+                return err(new AnalysisInputError("compare_web_screenshots", { cause }, [
+                    { path: [], reason: "invalid_format", message: cause.message },
+                ]));
             return err(providerError(cause, "compare_web_screenshots"));
         }
     }
     async #capture(input, options, operation) {
-        let targetSession;
-        try {
-            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, operation, options.signal);
-            const target = authorizeTarget(discovery, input);
-            const scopedInput = scopeToTargetOrigin(input, target);
-            targetSession = await openCdpTargetSession(discovery, target, operation, options.signal);
-            return await capturePage({
-                connection: targetSession.connection,
-                sessionId: targetSession.sessionId,
-                operation,
-                discovery,
-                target,
-                input: scopedInput,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
-                ...(options.progress === undefined
-                    ? {}
-                    : { progress: options.progress }),
-            });
-        }
-        finally {
-            if (targetSession !== undefined)
-                await closeCdpTargetSession(targetSession, CLEANUP_DOMAINS, options.signal);
-        }
+        return await withTargetSession(input, operation, options, async (session) => await capturePage({ ...session, operation }));
     }
 }
+/** Authorize one discovered target, run work in its session, and close REA's socket. */
+const withTargetSession = async (input, operation, options, work) => {
+    const endpoint = await openCdpEndpoint(input.cdp_endpoint, operation, options.signal);
+    let targetSession;
+    let output;
+    try {
+        const target = authorizeTarget(endpoint.discovery, input);
+        const scopedInput = scopeToTargetOrigin(input, target);
+        targetSession =
+            endpoint.connection === undefined
+                ? await openCdpTargetSession(endpoint.discovery, target, operation, options.signal)
+                : await attachCdpTargetSession(endpoint.connection, target, operation, options.signal);
+        output = await work({
+            connection: targetSession.connection,
+            sessionId: targetSession.sessionId,
+            discovery: endpoint.discovery,
+            target,
+            input: scopedInput,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.progress === undefined ? {} : { progress: options.progress }),
+        });
+    }
+    finally {
+        if (targetSession !== undefined)
+            await closeCdpTargetSession(targetSession, CLEANUP_DOMAINS, options.signal);
+        // An unadopted browser socket is closed here; closing is idempotent.
+        await endpoint.connection?.close();
+    }
+    // Cancellation during teardown must not publish the completed observation.
+    // Errors from work or cleanup still propagate through the try/finally above.
+    if (options.signal?.aborted === true)
+        throw new AnalysisCancelledError(operation, {
+            cause: options.signal.reason,
+        });
+    return output;
+};
 const selectTargets = (discovery, allowedOrigins) => {
     const allowed = [];
     let disallowedOrigin = 0;
@@ -235,7 +209,7 @@ const selectTargets = (discovery, allowedOrigins) => {
             attached: target.attached,
         });
     }
-    allowed.sort((left, right) => left.target_id.localeCompare(right.target_id));
+    allowed.sort((left, right) => compareUnicodeCodePoints(left.target_id, right.target_id));
     return {
         allowed,
         excluded: {
@@ -257,10 +231,12 @@ const scopeToTargetOrigin = (input, target) => {
         throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
     return { ...input, allowed_origins: [origin] };
 };
-const providerError = (cause, operation) => cause instanceof BrowserObservationError && cause.operation !== operation
+const providerError = (cause, operation, signal) => cause instanceof BrowserObservationError && cause.operation !== operation
     ? new BrowserObservationError(operation, cause.reason, { cause })
     : cause instanceof AnalysisError
         ? cause
-        : new ProviderAdapterError(CDP_BROWSER_PROVIDER_IDENTITY.id, operation, {
-            cause,
-        });
+        : signal?.aborted === true
+            ? new AnalysisCancelledError(operation, { cause })
+            : new ProviderAdapterError(CDP_BROWSER_PROVIDER_IDENTITY.id, operation, {
+                cause,
+            });