rea-agents 6.3.0 → 6.5.0

package/dist/domain/webNetworkCapture.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { jsonValueSchema } from "./jsonValue.js";
+import { localPathStringSchema } from "./localPath.js";
+import { qlogCaptureFactsSchema } from "./qlogCapture.js";
 /** Complete historical evidence budgets; exceeding a budget returns no partial capture. */
 export const WEB_NETWORK_CAPTURE_LIMITS = {
     inputBytes: 32 * 1024 * 1024,
@@ -7,13 +9,16 @@ export const WEB_NETWORK_CAPTURE_LIMITS = {
     timeoutMs: 30_000,
     depth: 64,
 };
+export const WEB_NETWORK_CAPTURE_FORMATS = [
+    "har",
+    "mitmproxy",
+    "saz",
+    "qlog",
+];
 /** Inspect an explicit retained capture without contacting its recorded destinations. */
 export const inspectWebNetworkCaptureInputSchema = z.strictObject({
-    capture_path: z
-        .string()
-        .min(1)
-        .describe("Absolute local HAR or mitmproxy capture path."),
-    format: z.enum(["har", "mitmproxy"]),
+    capture_path: localPathStringSchema.describe("Absolute local HAR, mitmproxy, Fiddler SAZ or aioquic qlog capture path."),
+    format: z.enum(WEB_NETWORK_CAPTURE_FORMATS),
     record_ordinals: z
         .array(z.number().int().nonnegative())
         .min(1)
@@ -24,6 +29,15 @@ export const inspectWebNetworkCaptureInputSchema = z.strictObject({
         .default([])
         .describe("Literal text excluded from capture payloads, byte/numeric projections, producer coordinates, artifact paths/digests and diagnostic text. Declaration strings are never persisted in Evidence parameters. Canonical contract keys, enums and provider identities remain intact."),
 });
+/** Read declarations through their owning schema for service and adapter failures. */
+export const captureSensitiveValues = (rawInput) => {
+    const parsed = inspectWebNetworkCaptureInputSchema.shape.sensitive_values.safeParse(typeof rawInput === "object" &&
+        rawInput !== null &&
+        "sensitive_values" in rawInput
+        ? rawInput.sensitive_values
+        : undefined);
+    return parsed.success ? parsed.data : [];
+};
 const pointerSchema = z
     .string()
     .describe("RFC 6901 pointer in the producer's reported object.");
@@ -44,21 +58,23 @@ const binaryBase = {
     pointer: pointerSchema,
     representation: z.enum(["producer-bytes", "har-base64-content"]),
 };
+const retainedBinaryDescriptorSchema = z.strictObject({
+    ...binaryBase,
+    state: z.literal("retained"),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
+const redactedBinaryDescriptorSchema = z.strictObject({
+    ...binaryBase,
+    state: z.literal("redacted"),
+    bytes: z.null(),
+    sha256: z.null(),
+});
+/** Exact byte facts shared by complete records and previews that omit content. */
+export const webNetworkCaptureBinaryDescriptorSchema = z.discriminatedUnion("state", [retainedBinaryDescriptorSchema, redactedBinaryDescriptorSchema]);
 const binarySchema = z.discriminatedUnion("state", [
-    z.strictObject({
-        ...binaryBase,
-        state: z.literal("retained"),
-        content_base64: z.string(),
-        bytes: z.number().int().nonnegative(),
-        sha256: z.string().regex(/^[0-9a-f]{64}$/),
-    }),
-    z.strictObject({
-        ...binaryBase,
-        state: z.literal("redacted"),
-        content_base64: z.null(),
-        bytes: z.null(),
-        sha256: z.null(),
-    }),
+    retainedBinaryDescriptorSchema.extend({ content_base64: z.string() }),
+    redactedBinaryDescriptorSchema.extend({ content_base64: z.null() }),
 ]);
 const numberSchema = z.strictObject({
     pointer: pointerSchema,
@@ -74,6 +90,10 @@ export const webNetworkCaptureRecordSchema = z.strictObject({
             reason: z.literal("explicit-sensitive-value"),
         }),
         z.strictObject({ kind: z.literal("json-pointer"), pointer: pointerSchema }),
+        z.strictObject({
+            kind: z.literal("archive-members"),
+            members: z.array(z.string()).min(1),
+        }),
         z.strictObject({
             kind: z.literal("byte-range"),
             offset: z.number().int().nonnegative(),
@@ -86,25 +106,15 @@ export const webNetworkCaptureRecordSchema = z.strictObject({
     redactions: z.array(redactionSchema),
     limitations: z.array(z.string()),
 });
-/** Historical capture inspection has file identity, producer provenance and explicit unknowns. */
-export const webNetworkCaptureSchema = z.strictObject({
-    artifact: z.strictObject({
-        path: z
-            .string()
-            .describe("Selected artifact path; empty when explicitly excluded from Evidence."),
-        sha256: z
-            .string()
-            .regex(/^[0-9a-f]{64}$/)
-            .nullable()
-            .describe("Observed artifact SHA-256; null only when explicitly excluded by a sensitive declaration."),
-        bytes: z.number().int().nonnegative(),
-    }),
-    format: z.enum(["har", "mitmproxy"]),
-    decoder: z.strictObject({
-        id: z.string().min(1),
-        name: z.string().min(1),
-        version: z.string().min(1),
-    }),
+/** The selected offline parser profile, independent of authenticated producer identity. */
+export const webNetworkCaptureDecoderSchema = z.strictObject({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    version: z.string().min(1),
+});
+/** Source coverage is shared by every offline decoder. */
+const payloadShape = {
+    decoder: webNetworkCaptureDecoderSchema,
     container: z.strictObject({
         reported: jsonValueSchema,
         numeric_literals: z.array(numberSchema),
@@ -113,6 +123,58 @@ export const webNetworkCaptureSchema = z.strictObject({
     }),
     total_records: z.number().int().nonnegative(),
     records: z.array(webNetworkCaptureRecordSchema),
+};
+const refineCoverage = (capture, context) => {
+    const seen = new Set();
+    for (const [index, record] of capture.records.entries()) {
+        if (record.ordinal >= capture.total_records || seen.has(record.ordinal)) {
+            context.addIssue({
+                code: "custom",
+                path: ["records", index, "ordinal"],
+                message: "Retained ordinals must be unique and within the declared capture total.",
+            });
+            return;
+        }
+        seen.add(record.ordinal);
+    }
+};
+/** Strict alternatives prevent undefined-valued facets from entering JSON Evidence. */
+export const webNetworkCapturePayloadSchema = z
+    .union([
+    z.strictObject({ ...payloadShape, qlog: qlogCaptureFactsSchema }),
+    z.strictObject(payloadShape),
+])
+    .superRefine(refineCoverage);
+/** Caller-selected file identity; explicit exclusions remain unknown. */
+export const webNetworkCaptureArtifactSchema = z.strictObject({
+    path: z
+        .string()
+        .describe("Selected artifact path; empty when explicitly excluded from Evidence."),
+    sha256: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .nullable()
+        .describe("Observed SHA-256; null only when explicitly excluded."),
+    bytes: z.number().int().nonnegative(),
+});
+const artifactShape = {
+    artifact: webNetworkCaptureArtifactSchema,
     runtime_attribution: z.literal("unknown"),
     limitations: z.array(z.string()),
-});
+};
+/** Qlog transport facts occur exactly on the qlog alternative. */
+export const webNetworkCaptureSchema = z
+    .discriminatedUnion("format", [
+    z.strictObject({
+        ...payloadShape,
+        ...artifactShape,
+        format: z.enum(["har", "mitmproxy", "saz"]),
+    }),
+    z.strictObject({
+        ...payloadShape,
+        ...artifactShape,
+        format: z.literal("qlog"),
+        qlog: qlogCaptureFactsSchema,
+    }),
+])
+    .superRefine(refineCoverage);

package/dist/domain/webNetworkCaptureCoordinates.js

@@ -14,6 +14,8 @@ export const excludeCaptureCoordinates = (value, sensitiveValues) => {
     const records = value.records.map((record) => {
         const location = (record.location.kind === "json-pointer" &&
             sensitive(record.location.pointer)) ||
+            (record.location.kind === "archive-members" &&
+                record.location.members.some(sensitive)) ||
             (record.location.kind === "byte-range" &&
                 (sensitive(String(record.location.offset)) ||
                     sensitive(String(record.location.bytes))))
@@ -44,8 +46,27 @@ export const excludeCaptureCoordinates = (value, sensitiveValues) => {
         numeric_literals: sidecars(value.container.numeric_literals),
         redactions: sidecars(value.container.redactions),
     };
+    const qlog = value.format === "qlog"
+        ? {
+            ...value.qlog,
+            traces: value.qlog.traces.map((trace) => {
+                if (trace.location.kind !== "json-pointer" ||
+                    !sensitive(trace.location.pointer))
+                    return trace;
+                excluded = true;
+                return {
+                    ...trace,
+                    location: {
+                        kind: "unknown",
+                        reason: "explicit-sensitive-value",
+                    },
+                };
+            }),
+        }
+        : undefined;
     return {
         ...value,
+        ...(qlog === undefined ? {} : { qlog }),
         container,
         records,
         limitations: excluded

package/dist/domain/webRuntime.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { browserAllowedOriginsSchema, browserEndpointSchema, } from "./browserObservation.js";
-import { browserVersionSchema } from "./browserObservationSchemas.js";
 import { jsonObjectSchema } from "./jsonValue.js";
 // CDP positions are zero-based and relative to the resource named by url.
 // With a script ID that is the script's enclosing resource: the script file,

package/dist/domain/webScreenshot.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { browserCompletenessSchema } from "./browserCompleteness.js";
-import { browserAllowedOriginsSchema, browserEndpointSchema, } from "./browserObservation.js";
+import { browserAllowedOriginsSchema, browserObservationEndpointSchema, } from "./browserObservation.js";
 import { browserVersionSchema } from "./browserObservationSchemas.js";
 /** Self-verifying inline PNG artifact for CLI/MCP parity. */
 export const webScreenshotArtifactSchema = z
@@ -26,7 +26,7 @@ export const webScreenshotArtifactSchema = z
 });
 /** Input for one read-only visible-viewport screenshot. */
 export const captureWebScreenshotInputSchema = z.strictObject({
-    cdp_endpoint: browserEndpointSchema,
+    cdp_endpoint: browserObservationEndpointSchema,
     allowed_origins: browserAllowedOriginsSchema,
     target_id: z.string().trim().min(1),
 });

package/dist/domain/webScriptArtifacts.js

@@ -1,12 +1,10 @@
 import { z } from "zod";
 import { digestSchema } from "./digests.js";
+import { localPathStringSchema } from "./localPath.js";
 import { webScriptExportManifestSchema } from "./webScriptExport.js";
 /** Select one source from an existing captured-script export. */
 export const selectedWebScriptInputSchema = z.strictObject({
-    manifest_path: z
-        .string()
-        .min(1)
-        .describe("Absolute export_web_scripts manifest path"),
+    manifest_path: localPathStringSchema.describe("Absolute export_web_scripts manifest path"),
     script_index: z
         .number()
         .int()

package/dist/domain/webScriptExport.js

@@ -2,16 +2,11 @@ import { z } from "zod";
 import { browserCompletenessSchema } from "./browserCompleteness.js";
 import { browserScenarioCompletenessSchema } from "./browserScenarioCaptureValues.js";
 import { digestSchema, prefixedDigestSchema } from "./digests.js";
+import { localPathStringSchema } from "./localPath.js";
 /** Export already captured scripts into one absent, caller-selected directory. */
 export const exportWebScriptsInputSchema = z.strictObject({
-    capture_path: z
-        .string()
-        .min(1)
-        .describe("Absolute filesystem path to saved inspect_web_page or capture_browser_scenario JSON, normalized result or complete Evidence"),
-    output_directory: z
-        .string()
-        .min(1)
-        .describe("Absolute absent filesystem directory for verified scripts and manifest; parent directory must exist"),
+    capture_path: localPathStringSchema.describe("Absolute filesystem path to saved inspect_web_page or capture_browser_scenario JSON, normalized result or complete Evidence"),
+    output_directory: localPathStringSchema.describe("Absolute absent filesystem directory for verified scripts and manifest; parent directory must exist"),
 });
 const sourceSchema = z.discriminatedUnion("kind", [
     z.strictObject({
@@ -46,6 +41,9 @@ export const exportedWebScriptSchema = z.strictObject({
             redacted: z.boolean().nullable(),
             representation: z.enum([
                 "debugger-source-utf8",
+                "playwright-response-body-bytes",
+                // Accept already-saved exports from before the response representation
+                // was narrowed to the Playwright API result.
                 "browser-decoded-response-bytes",
             ]),
         }),

package/dist/domain/webScriptExportError.js

@@ -4,10 +4,16 @@ export class WebScriptExportError extends ArtifactOperationError {
     userMessage;
     cleanupIncomplete;
     cleanupResources;
-    constructor(reason, target, diagnostic, residualPaths = []) {
-        super("export_web_scripts", reason);
+    constructor(reason, target, diagnostic, options = {}) {
+        super("export_web_scripts", reason, undefined, undefined, options);
         this.userMessage = `Script export failed for ${target}: ${diagnostic}`;
-        this.cleanupResources = residualPaths;
-        this.cleanupIncomplete = residualPaths.length > 0;
+        this.cleanupResources = [
+            ...new Set([
+                ...(options.cleanup?.resources ?? []),
+                ...(options.residualPaths ?? []),
+            ]),
+        ];
+        this.cleanupIncomplete =
+            options.cleanup !== undefined || (options.residualPaths?.length ?? 0) > 0;
     }
 }

package/dist/domain/webScriptExportPlan.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { urlDeclaresQueryOrFragment } from "./urlComponents.js";
 const hash = (text) => createHash("sha256").update(text).digest("hex");
 const PORTABLE_SEGMENT = /^[A-Za-z0-9_~.-]+$/u;
 const RESERVED_SEGMENT = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;
@@ -18,7 +19,7 @@ export const planWebScriptExport = (scripts) => {
             };
         const candidate = candidates[index];
         const reason = conflicts.has(index)
-            ? "Captured paths collide by content version, case, or file/directory prefix."
+            ? "Captured paths collide by content version or file/directory prefix."
             : (candidate?.reason ?? null);
         const path = reason === null ? candidate?.path : undefined;
         return {
@@ -66,16 +67,16 @@ const candidatePath = (script) => {
         };
     return {
         path: `origins/${hash(url.origin)}/${parts.join("/")}`,
-        reason: url.search !== "" ||
-            url.hash !== "" ||
+        reason: urlDeclaresQueryOrFragment(url) ||
             url.username !== "" ||
             url.password !== ""
             ? "URL query, fragment, or credentials cannot select a canonical local module."
             : null,
     };
 };
-// Register every prefix so case collisions in parent directories and a file
-// conflicting with a directory isolate all affected sources, not just the last.
+// Register every exact prefix so a repeated path, or a file that is also a
+// directory prefix, isolates every affected source. Case-distinct spellings
+// stay distinct until the destination filesystem reports a collision.
 const conflictingPaths = (candidates) => {
     const prefixes = new Map();
     candidates.forEach(({ path }, index) => {
@@ -84,23 +85,16 @@ const conflictingPaths = (candidates) => {
         const parts = path.split("/");
         parts.forEach((_, position) => {
             const spelling = parts.slice(0, position + 1).join("/");
-            const key = spelling.toLowerCase();
-            const entry = prefixes.get(key) ?? {
-                spellings: new Set(),
-                indices: [],
-                files: [],
-            };
-            entry.spellings.add(spelling);
+            const entry = prefixes.get(spelling) ?? { indices: [], files: [] };
             entry.indices.push(index);
             if (position === parts.length - 1)
                 entry.files.push(index);
-            prefixes.set(key, entry);
+            prefixes.set(spelling, entry);
         });
     });
     const conflicts = new Set();
     for (const entry of prefixes.values())
-        if (entry.spellings.size > 1 ||
-            entry.files.length > 1 ||
+        if (entry.files.length > 1 ||
             (entry.files.length > 0 && entry.indices.length > entry.files.length))
             for (const index of entry.indices)
                 conflicts.add(index);

package/dist/domain/webSourceLocation.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { digestSchema } from "./digests.js";
+import { localPathStringSchema } from "./localPath.js";
 import { exportedWebScriptSchema } from "./webScriptExport.js";
 import { capturedWebManifestIdentitySchema, selectedWebScriptInputSchema, webArtifactFileSchema, } from "./webScriptArtifacts.js";
 /** JavaScript source-map positions use UTF-16 columns and one-based lines. */
@@ -10,10 +11,7 @@ export const webSourcePositionSchema = z.strictObject({
 /** Trace one explicit generated position through an explicitly paired local map. */
 export const webSourceLocationInputSchema = selectedWebScriptInputSchema.extend({
     source_map: z.strictObject({
-        path: z
-            .string()
-            .min(1)
-            .describe("Absolute local source-map path; no fetch"),
+        path: localPathStringSchema.describe("Absolute local source-map path; no fetch"),
         url: z
             .string()
             .min(1)
@@ -63,11 +61,22 @@ export const webSourceMapReportSchema = z.strictObject({
     source_map_sha256: digestSchema,
     url_context: z.string().min(1),
     engine: z.strictObject({ id: z.string().min(1), version: z.string().min(1) }),
-    runtime: z.strictObject({
-        id: z.string().min(1),
-        version: z.string().min(1),
-        v8_heap_limit_bytes: z.number().int().min(1),
-    }),
+    runtime: z.discriminatedUnion("id", [
+        z.strictObject({
+            id: z.literal("node-v8"),
+            version: z.string().min(1),
+            v8_heap_limit_bytes: z.number().int().min(1),
+        }),
+        // Bun reports V8-shaped heap statistics but does not enforce V8 heap flags.
+        // On Windows REA instead enforces a Job Object commit limit on the codec.
+        z.strictObject({
+            id: z.literal("bun"),
+            version: z.string().min(1),
+            node_compatibility_version: z.string().min(1),
+            v8_heap_limit_bytes: z.null(),
+            process_memory_limit_bytes: z.number().int().min(1).nullable(),
+        }),
+    ]),
     format: z.enum(["regular", "indexed"]),
     reported_file: z.string().nullable(),
     lookup: z.strictObject({
@@ -88,6 +97,8 @@ export const WEB_SOURCE_MAP_LIMITS = {
     decodedRecords: 262144,
     sectionDepth: 64,
     decodeTimeoutMs: 20000,
+    /** V8 old-generation heap for the codec, and its Bun process budget. */
+    codecHeapMiB: 192,
 };
 /** Selected capture/map byte identities and complete point attribution inline. */
 export const webSourceLocationResultSchema = webSourceMapReportSchema.extend({

package/dist/domain/zipPackageFormat.js

@@ -1,3 +1,16 @@
+/** ZIP-backed application package families that share the hardened archive reader. */
+export const ZIP_PACKAGE_FORMATS = [
+    "zip",
+    "ipa",
+    "apk",
+    "msix",
+    "appx",
+    "hap",
+    "hsp",
+    "app-pack",
+];
+/** All ZIP package families share archive ownership and inventory coverage. */
+export const isZipPackageFormat = (format) => ZIP_PACKAGE_FORMATS.some((candidate) => candidate === format);
 /** Recognize local-header, empty-archive, or split-archive ZIP signatures, not archive validity. */
 export const hasZipSignature = (bytes) => bytes.length >= 4 &&
     bytes[0] === 0x50 &&
@@ -9,7 +22,12 @@ export const hasZipSignature = (bytes) => bytes.length >= 4 &&
  * Classify a ZIP-backed package by its complete lower-cased path suffix.
  *
  * This is deliberately extension-only. Callers must separately verify ZIP
- * magic before trusting the classification for a root input.
+ * magic before trusting the classification for a root input. HarmonyOS `.har`
+ * is intentionally absent: the suffix also names HTTP Archive JSON, so a
+ * Harmony shared archive is only established from verified ZIP bytes. The
+ * HarmonyOS App Pack suffix `.app` is also absent here: it applies only to
+ * root inputs (see `classifyAndHashRoot`), because a nested ZIP entry ending
+ * in `.app` inside another package, such as an IPA, is not an App Pack.
  */
 export const zipPackageFormatForPath = (path) => {
     const lower = path.toLowerCase();
@@ -17,11 +35,22 @@ export const zipPackageFormatForPath = (path) => {
         return "zip";
     if (lower.endsWith(".ipa"))
         return "ipa";
-    if (lower.endsWith(".apk") || lower.endsWith(".aab"))
+    // An Android App Bundle is a ZIP archive, not a standalone APK.
+    if (lower.endsWith(".apk"))
         return "apk";
     if (lower.endsWith(".msix") || lower.endsWith(".msixbundle"))
         return "msix";
     if (lower.endsWith(".appx") || lower.endsWith(".appxbundle"))
         return "appx";
+    if (lower.endsWith(".hap"))
+        return "hap";
+    if (lower.endsWith(".hsp"))
+        return "hsp";
     return undefined;
 };
+/** Inventory lists entries, not all bytes surrounding the central directory. */
+export const ZIP_NON_ENTRY_LIMITATION = "ZIP inventory lists central-directory entries only. Non-entry bytes, including an APK Signing Block before the central directory or a ZIP comment after it, are not occurrences.";
+/** Recognize the same inventory scope in current and previously retained Evidence. */
+export const isZipInventoryScopeLimitation = (limitation) => limitation === ZIP_NON_ENTRY_LIMITATION ||
+    limitation ===
+        "ZIP inventory lists central-directory entries only. Bytes after the central directory, including an APK Signing Block or a ZIP comment, are not occurrences.";

package/dist/domain/zodCollectionSteps.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/**
+ * An array schema's own constraints, such as a minimum length, without its
+ * element schema. Pair it with {@link parseElementSteps} to validate a large
+ * collection in cooperative steps.
+ */
+export const arrayContainerSchema = (array) => array.clone({ ...array.def, element: z.unknown() });
+/** Elements validated between yields, in the issues and paths a whole-array parse reports. */
+export function* parseElementSteps(element, values, path, issues) {
+    const parsed = [];
+    for (const [index, value] of values.entries()) {
+        if (index % 64 === 0)
+            yield;
+        const result = element.safeParse(value);
+        if (result.success)
+            parsed.push(result.data);
+        else
+            issues.push(...result.error.issues.map((issue) => ({
+                ...issue,
+                path: [...path, index, ...issue.path],
+            })));
+    }
+    return parsed;
+}