rea-agents 2.4.0 → 3.0.0

package/dist/domain/webCaptureDiff.js

@@ -3,7 +3,8 @@ import canonicalize from "canonicalize";
 import { z } from "zod";
 import { webPageInspectionSchema, } from "./browserObservation.js";
 import { webMcpDiscoverySchema, } from "./webMcpDiscovery.js";
-const captureSnapshotSchema = z.object({
+/** One normalized passive page snapshot accepted by capture comparison. */
+export const captureSnapshotSchema = z.object({
     inspection: webPageInspectionSchema,
     webmcp: webMcpDiscoverySchema.nullable().default(null),
 });
@@ -24,6 +25,13 @@ const dimensionSchema = z.object({
     omitted_changes: z.number().int().min(0),
     reason: z.string().nullable(),
 });
+const legacyUnknownDimension = {
+    status: "unknown",
+    total_changes: 0,
+    changes: [],
+    omitted_changes: 0,
+    reason: "Dimension was not recorded by this version 1 capture diff.",
+};
 /** Completeness-aware changes across stable browser evidence dimensions. */
 export const webCaptureDiffSchema = z.object({
     schema_version: z.literal(1),
@@ -37,39 +45,17 @@ export const webCaptureDiffSchema = z.object({
         network: dimensionSchema,
         metadata: dimensionSchema,
         webmcp: dimensionSchema,
+        accessibility: dimensionSchema.default(legacyUnknownDimension),
+        storage: dimensionSchema.default(legacyUnknownDimension),
     }),
     limitations: z.array(z.string()),
 });
 /** Compare normalized observations without treating incomplete absence as proof. */
 export const compareWebCaptures = (input) => {
-    let remaining = input.max_changes;
-    const dimension = (before, after, complete, reason) => {
-        const all = compareIdentities(before, after);
-        const retained = all.slice(0, remaining);
-        remaining -= retained.length;
-        return {
-            status: all.length > 0 ? "changed" : complete ? "unchanged" : "unknown",
-            total_changes: all.length,
-            changes: retained,
-            omitted_changes: all.length - retained.length,
-            reason: all.length === 0 && !complete ? reason : null,
-        };
-    };
+    const remaining = { value: input.max_changes };
     const before = input.before.inspection;
     const after = input.after.inspection;
-    const dimensions = {
-        dom_structure: dimension(singleton("document", digest(domProjection(before))), singleton("document", digest(domProjection(after))), sectionsComplete(before, ["frames", "dom"]) &&
-            sectionsComplete(after, ["frames", "dom"]), "DOM or frame capture was incomplete in at least one observation."),
-        scripts: dimension(keyed(before.scripts.items.map(scriptProjection), (item) => item.script_key), keyed(after.scripts.items.map(scriptProjection), (item) => item.script_key), sectionsComplete(before, ["scripts"]) &&
-            sectionsComplete(after, ["scripts"]), "Script inventory was incomplete in at least one observation."),
-        resources: dimension(keyed(before.resources, (item) => item.resource_key), keyed(after.resources, (item) => item.resource_key), sectionsComplete(before, ["resources"]) &&
-            sectionsComplete(after, ["resources"]), "Resource inventory was incomplete in at least one observation."),
-        network: dimension(networkMap(before), networkMap(after), sectionsComplete(before, ["network_requests"]) &&
-            sectionsComplete(after, ["network_requests"]), "Network capture is attach-window limited or incomplete."),
-        metadata: dimension(singleton("metadata", digest(metadataProjection(before))), singleton("metadata", digest(metadataProjection(after))), sectionsComplete(before, ["metadata"]) &&
-            sectionsComplete(after, ["metadata"]), "Safe metadata capture was incomplete in at least one observation."),
-        webmcp: dimension(webMcpMap(input.before.webmcp), webMcpMap(input.after.webmcp), webMcpComplete(input.before.webmcp) && webMcpComplete(input.after.webmcp), "WebMCP discovery was unavailable or incomplete in at least one capture."),
-    };
+    const dimensions = compareWebCaptureDimensions(input, remaining);
     const statuses = Object.values(dimensions).map(({ status }) => status);
     return webCaptureDiffSchema.parse({
         schema_version: 1,
@@ -90,6 +76,8 @@ export const compareWebCaptures = (input) => {
         limitations: [
             "A changed status proves an observed difference; an unknown status means absence could not be established from capture completeness.",
             "Network comparison covers only activity observed after each CDP attachment.",
+            "Accessibility roles, ignored state, text, and hierarchy are compared only when the accessibility tree was fully captured and text capture was approved and not truncated.",
+            "Storage key inventories are compared only when approved and complete; usage and quota are compared only when reported. Redacted content is compared through complete SHA-256 fingerprints.",
         ],
     });
 };
@@ -108,6 +96,54 @@ const compareIdentities = (before, after) => {
     return changes.sort((left, right) => left.identity.localeCompare(right.identity) ||
         left.change.localeCompare(right.change));
 };
+const compareDimension = (remaining) => (before, after, complete, reason) => {
+    const all = compareIdentities(before, after);
+    const retained = all.slice(0, remaining.value);
+    remaining.value -= retained.length;
+    return {
+        status: all.length > 0 ? "changed" : complete ? "unchanged" : "unknown",
+        total_changes: all.length,
+        changes: retained,
+        omitted_changes: all.length - retained.length,
+        reason: all.length === 0 && !complete ? reason : null,
+    };
+};
+const accessibilityDimension = (before, after, remaining) => {
+    const beforeAccess = accessibilityComparable(before);
+    const afterAccess = accessibilityComparable(after);
+    const textComparable = beforeAccess.text && afterAccess.text;
+    const nodesComparable = beforeAccess.nodes && afterAccess.nodes;
+    return compareDimension(remaining)(singleton("accessibility_tree", digest(accessibilityProjection(before.accessibility, textComparable, nodesComparable))), singleton("accessibility_tree", digest(accessibilityProjection(after.accessibility, textComparable, nodesComparable))), beforeAccess.complete && afterAccess.complete, "Accessibility tree or text capture was incomplete in at least one observation.");
+};
+const storageDimension = (before, after, remaining) => {
+    const keysComplete = storageKeysComparable(before) && storageKeysComparable(after);
+    const usageComplete = before.storage.usage_bytes !== null &&
+        after.storage.usage_bytes !== null &&
+        before.storage.quota_bytes !== null &&
+        after.storage.quota_bytes !== null;
+    const comparableFingerprints = storageFingerprintIdentities(before.storage, after.storage);
+    return compareDimension(remaining)(storageMap(before.storage, keysComplete, usageComplete, comparableFingerprints), storageMap(after.storage, keysComplete, usageComplete, comparableFingerprints), storageComparable(before, after, keysComplete, usageComplete), "Storage fingerprints, inventories, usage, or quota were unavailable or truncated in at least one observation.");
+};
+const compareWebCaptureDimensions = (input, remaining) => {
+    const before = input.before.inspection;
+    const after = input.after.inspection;
+    const dimension = compareDimension(remaining);
+    return {
+        dom_structure: dimension(singleton("document", digest(domProjection(before))), singleton("document", digest(domProjection(after))), sectionsComplete(before, ["frames", "dom"]) &&
+            sectionsComplete(after, ["frames", "dom"]), "DOM or frame capture was incomplete in at least one observation."),
+        scripts: dimension(keyed(before.scripts.items.map(scriptProjection), (item) => item.script_key), keyed(after.scripts.items.map(scriptProjection), (item) => item.script_key), sectionsComplete(before, ["scripts"]) &&
+            sectionsComplete(after, ["scripts"]), "Script inventory was incomplete in at least one observation."),
+        resources: dimension(keyed(before.resources, (item) => item.resource_key), keyed(after.resources, (item) => item.resource_key), sectionsComplete(before, ["resources"]) &&
+            sectionsComplete(after, ["resources"]), "Resource inventory was incomplete in at least one observation."),
+        network: dimension(networkMap(before), networkMap(after), sectionsComplete(before, ["network_requests"]) &&
+            sectionsComplete(after, ["network_requests"]), "Network capture is attach-window limited or incomplete."),
+        metadata: dimension(singleton("metadata", digest(metadataProjection(before))), singleton("metadata", digest(metadataProjection(after))), sectionsComplete(before, ["metadata"]) &&
+            sectionsComplete(after, ["metadata"]), "Safe metadata capture was incomplete in at least one observation."),
+        webmcp: dimension(webMcpMap(input.before.webmcp), webMcpMap(input.after.webmcp), webMcpComplete(input.before.webmcp) && webMcpComplete(input.after.webmcp), "WebMCP discovery was unavailable or incomplete in at least one capture."),
+        accessibility: accessibilityDimension(before, after, remaining),
+        storage: storageDimension(before, after, remaining),
+    };
+};
 const keyed = (values, identity) => new Map(values.map((value) => [identity(value), digest(value)]));
 const networkMap = (inspection) => {
     const grouped = new Map();
@@ -182,3 +218,81 @@ const digest = (value) => {
         throw new TypeError("Expected canonical JSON");
     return createHash("sha256").update(encoded).digest("hex");
 };
+const accessibilityComparable = (inspection) => {
+    const text = inspection.accessibility.text_capture.status === "included" &&
+        inspection.accessibility.text_capture.excluded_fields === 0 &&
+        inspection.accessibility.text_capture.truncated_fields === 0;
+    const nodes = inspection.accessibility.total_nodes ===
+        inspection.accessibility.nodes.length;
+    const complete = text && nodes && sectionsComplete(inspection, ["accessibility"]);
+    return { text, nodes, complete };
+};
+const accessibilityProjection = (accessibility, includeText, includeNodes) => {
+    const result = {
+        total_nodes: accessibility.total_nodes,
+    };
+    if (!includeNodes)
+        return result;
+    const nodeIndexes = new Map(accessibility.nodes.map((node, index) => [node.node_id, index]));
+    result.nodes = accessibility.nodes.map((node) => ({
+        parent_index: node.parent_id === null ? null : (nodeIndexes.get(node.parent_id) ?? -1),
+        role: node.role,
+        ignored: node.ignored,
+        states: node.states,
+        ...(includeText ? { name: node.name, description: node.description } : {}),
+    }));
+    return result;
+};
+const storageKeysComparable = (inspection) => sectionsComplete(inspection, ["storage_keys"]);
+const storageComparable = (before, after, keysComplete, usageComplete) => keysComplete &&
+    usageComplete &&
+    before.storage.fingerprints_complete &&
+    after.storage.fingerprints_complete;
+const storageMap = (storage, includeKeys, includeUsage, fingerprintIdentities) => {
+    const map = new Map([
+        [
+            "storage:summary",
+            digest({
+                origin: storage.origin,
+                values_redacted: storage.values_redacted,
+                ...(includeUsage
+                    ? {
+                        usage_bytes: storage.usage_bytes,
+                        quota_bytes: storage.quota_bytes,
+                    }
+                    : {}),
+            }),
+        ],
+    ]);
+    if (!includeKeys)
+        return map;
+    const add = (kind, keys) => {
+        for (const key of keys) {
+            map.set(`storage:${kind}:${key}`, digest(key));
+        }
+    };
+    add("local_storage", storage.local_storage_keys);
+    add("session_storage", storage.session_storage_keys);
+    add("indexed_db", storage.indexed_db_names);
+    add("cache", storage.cache_names);
+    for (const fingerprint of storage.content_fingerprints) {
+        const identity = `${fingerprint.scope}:${fingerprint.identity_sha256}`;
+        if (!fingerprintIdentities.has(identity))
+            continue;
+        map.set(`storage:content:${identity}`, digest(fingerprint.value_sha256));
+    }
+    return map;
+};
+const storageFingerprintIdentities = (before, after) => {
+    const beforeComplete = completeStorageFingerprints(before);
+    const afterComplete = completeStorageFingerprints(after);
+    if (before.fingerprints_complete && after.fingerprints_complete)
+        return new Set([...beforeComplete.keys(), ...afterComplete.keys()]);
+    return new Set([...beforeComplete.keys()].filter((identity) => afterComplete.has(identity)));
+};
+const completeStorageFingerprints = (storage) => new Map(storage.content_fingerprints
+    .filter(({ complete }) => complete)
+    .map(({ scope, identity_sha256, value_sha256 }) => [
+    `${scope}:${identity_sha256}`,
+    value_sha256,
+]));

package/dist/domain/webScreenshot.js

@@ -4,7 +4,7 @@ import { browserCompletenessSchema } from "./browserCompleteness.js";
 import { browserAllowedOriginsSchema, browserEndpointSchema, } from "./browserObservation.js";
 const MAX_SCREENSHOT_BYTES = 8 * 1_024 * 1_024;
 /** Self-verifying inline PNG artifact for CLI/MCP parity. */
-const webScreenshotArtifactSchema = z
+export const webScreenshotArtifactSchema = z
     .object({
     uri: z.string().regex(/^rea:\/\/web-screenshot\/sha256\/[a-f0-9]{64}$/u),
     sha256: z.string().regex(/^[a-f0-9]{64}$/u),

package/dist/dotnet/ManagedStaticProvider.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { MANAGED_STATIC_PROVIDER } from "../application/InvestigationProviders.js";
@@ -48,6 +49,7 @@ export class ManagedStaticProvider {
 }
 class ManagedStaticClient {
     target;
+    #snapshotBytes;
     constructor(target) {
         this.target = target;
     }
@@ -65,12 +67,18 @@ class ManagedStaticClient {
             const metadata = await stat(this.target.path);
             if (metadata.size > maxFileBytes)
                 return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Artifact size ${String(metadata.size)} exceeds max_file_bytes ${String(maxFileBytes)}.`));
-            const bytes = await readFile(this.target.path, options?.signal === undefined ? undefined : { signal: options.signal });
-            if (bytes.length > maxFileBytes)
+            const snapshot = this.#snapshotBytes;
+            const observed = snapshot === undefined
+                ? await readManagedSnapshot(this.target.path, options?.signal)
+                : await hashManagedSource(this.target.path, options?.signal);
+            if (observed.byteLength > maxFileBytes)
                 return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Artifact grew beyond max_file_bytes ${String(maxFileBytes)} while it was read.`));
-            const observedDigest = createHash("sha256").update(bytes).digest("hex");
-            if (observedDigest !== this.target.sha256)
-                return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${this.target.sha256}, observed ${observedDigest} at ${this.target.path}`));
+            if (observed.sha256 !== this.target.sha256)
+                return err(new EvidenceIntegrityError(`Managed artifact digest changed after open: expected ${this.target.sha256}, observed ${observed.sha256} at ${this.target.path}`));
+            const bytes = snapshot ?? observed.bytes;
+            if (bytes === undefined)
+                throw new TypeError("Managed snapshot bytes are unavailable");
+            this.#snapshotBytes = bytes;
             const result = inspectManagedOperation(operation, parameters, bytes, this.target);
             return ok(createAnalysisExecution(result, IDENTITY, {
                 rawResult: null,
@@ -86,9 +94,30 @@ class ManagedStaticClient {
         }
     }
     close() {
+        this.#snapshotBytes = undefined;
         return Promise.resolve();
     }
 }
+const readManagedSnapshot = async (path, signal) => {
+    const bytes = await readFile(path, signal === undefined ? undefined : { signal });
+    return {
+        byteLength: bytes.length,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        bytes,
+    };
+};
+const hashManagedSource = async (path, signal) => {
+    const digest = createHash("sha256");
+    let byteLength = 0;
+    const stream = createReadStream(path, signal === undefined ? undefined : { signal });
+    for await (const chunk of stream) {
+        if (!Buffer.isBuffer(chunk))
+            throw new TypeError("Managed source stream returned non-buffer data");
+        byteLength += chunk.length;
+        digest.update(chunk);
+    }
+    return { byteLength, sha256: digest.digest("hex") };
+};
 const isManagedOperation = (operation) => MANAGED_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const limitationsFor = (operation) => Object.freeze(operation === "inspect_managed_artifact"
     ? [