rea-agents 2.3.0 → 2.5.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/domain/zipPackageFormat.js

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export const zipPackageFormatForPath = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".zip"))
+        return "zip";
+    if (lower.endsWith(".ipa"))
+        return "ipa";
+    if (lower.endsWith(".apk") || lower.endsWith(".aab"))
+        return "apk";
+    if (lower.endsWith(".msix") || lower.endsWith(".msixbundle"))
+        return "msix";
+    if (lower.endsWith(".appx") || lower.endsWith(".appxbundle"))
+        return "appx";
+    return undefined;
+};

package/dist/generatedPackageMetadata.js

@@ -1,7 +1,7 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "2.3.0", // x-release-please-version
+    version: "2.5.0", // x-release-please-version
     serverSdkVersion: "2.0.0-beta.4",
     clientSdkVersion: "2.0.0-beta.4",
     coreSdkVersion: "2.0.0-beta.4",

package/dist/ghidra/GhidraDefaults.js

@@ -17,4 +17,4 @@ export const GHIDRA_MAX_QUEUED_REQUESTS = 32;
 /** Maximum encoded response line accepted from the Java bridge. */
 export const GHIDRA_MAX_LINE_BYTES = 1024 * 1024;
 /** Version of REA's Java bridge handshake and request protocol. */
-export const GHIDRA_BRIDGE_VERSION = 4;
+export const GHIDRA_BRIDGE_VERSION = 5;

package/dist/ghidra/GhidraFunctionValues.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
-import { functionDossierSchema, } from "../domain/hopperValues.js";
+import { functionInstructionWindowSchema, functionDossierSchema, } from "../domain/hopperValues.js";
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { ghidraBoundedIdentifierSchema, ghidraCanonicalAddressSchema, } from "./GhidraInventoryValues.js";
@@ -12,6 +12,7 @@ export const GHIDRA_FUNCTION_OPERATIONS = [
     "procedure_callers",
     "procedure_info",
     "procedure_pseudo_code",
+    "read_function_instructions",
     "procedure_references",
     "xrefs",
 ];
@@ -66,6 +67,13 @@ const inputSchemas = {
     procedure_callers: z.object(directProcedure).strict(),
     procedure_info: z.object(directProcedure).strict(),
     procedure_pseudo_code: z.object(directProcedure).strict(),
+    read_function_instructions: z
+        .object({
+        ...directProcedure,
+        offset: z.number().int().min(0).max(100_000).default(0),
+        limit: z.number().int().min(1).max(500).default(64),
+    })
+        .strict(),
     procedure_references: z
         .object({
         ...directProcedure,
@@ -235,6 +243,9 @@ const ghidraFunctionDossier = functionDossierSchema.superRefine((value, context)
             message: "Ghidra dossier omitted required uncertainty limitations",
         });
 });
+const ghidraFunctionInstructionWindow = functionInstructionWindowSchema
+    .extend({ procedure: procedureIdentity })
+    .strict();
 const resultSchemas = {
     analyze_function: ghidraFunctionDossier,
     procedure_assembly: z.string(),
@@ -242,6 +253,7 @@ const resultSchemas = {
     procedure_callers: z.array(ghidraCanonicalAddressSchema),
     procedure_info: procedureInfo,
     procedure_pseudo_code: z.string().nullable(),
+    read_function_instructions: ghidraFunctionInstructionWindow,
     procedure_references: procedureReferences,
     xrefs: z.array(ghidraCanonicalAddressSchema),
 };

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -26,6 +26,7 @@ const PAGINATED_OPERATIONS = new Set([
     "search_procedures",
     "search_strings",
     "procedure_references",
+    "read_function_instructions",
     "analyze_function",
 ]);
 const SEARCH_OPERATIONS = new Set([
@@ -93,6 +94,12 @@ export const limitationsFor = (operation) => {
                 "Pseudocode is Ghidra decompiler output, not original source and not text-equivalent to Hopper output; each decompile has a 30-second native deadline.",
                 "External functions and functions without an analyzable body return null; other decompiler failures remain explicit.",
             ];
+        case "read_function_instructions":
+            return [
+                ...common,
+                "This bounded fast path reads only the requested function instruction window and does not invoke the decompiler or whole-program string/name inventories.",
+                "Instruction text is Ghidra-specific and does not claim textual equivalence with Hopper output.",
+            ];
         case "procedure_assembly":
             return [
                 ...common,

package/dist/hopper/HopperCleanup.js

@@ -0,0 +1,158 @@
+import { HopperProcessError } from "../domain/errors.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { createOwnedHopperShutdownDiagnostic, providerCleanupFailure, } from "./HopperDiagnostics.js";
+import { isHopperCleanupRequired, isHopperShutdownAcknowledgement, } from "./HopperSessionValues.js";
+/** Close Hopper phases and retain every resource whose cleanup is unverified. */
+export const cleanupHopperSession = async (input) => {
+    const state = {
+        issues: [],
+        resources: new Set(),
+        cleanupResult: undefined,
+        shutdownConfirmed: false,
+        ownedProcessStopped: false,
+    };
+    await report(input.progress, 0, "requesting Hopper document shutdown");
+    await requestShutdown(input, state);
+    await report(input.progress, 0.35, "releasing Hopper bridge transport");
+    input.releaseTransport(input.socket);
+    await stopProcess(input, state);
+    recordUnconfirmedDocument(input, state);
+    await report(input.progress, 0.75, "removing Hopper private runtime files");
+    await closeRuntimeRoot(input.runtimeRoot, state);
+    return cleanupOutcome(input, state);
+};
+const requestShutdown = async (input, state) => {
+    if (input.socket === undefined ||
+        input.socket.destroyed ||
+        input.activeRequest !== null) {
+        if (input.activeRequest !== null)
+            input.logger.warn({
+                method: input.activeRequest.operation,
+                callerState: input.activeRequest.callerState,
+            }, "Hopper shutdown skipped because a bridge operation remained active");
+        return;
+    }
+    const shutdown = await input
+        .request("shutdown")
+        .catch(() => err(new HopperProcessError(null)));
+    if (shutdown.ok &&
+        isHopperCleanupRequired(shutdown.value) &&
+        input.launch?.shutdownByCleanup === true &&
+        input.launch.cleanup !== undefined) {
+        state.cleanupResult = await input.launch
+            .cleanup()
+            .catch(providerCleanupFailure);
+        if (!state.cleanupResult.cleaned) {
+            state.shutdownConfirmed = await fallbackDocumentShutdown(input);
+            state.cleanupResult = await input.launch
+                .cleanup()
+                .catch(providerCleanupFailure);
+        }
+    }
+    else if (shutdown.ok) {
+        state.shutdownConfirmed = isHopperShutdownAcknowledgement(shutdown.value);
+    }
+    if (!shutdown.ok ||
+        (!state.shutdownConfirmed && state.cleanupResult === undefined))
+        input.logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
+};
+const fallbackDocumentShutdown = async (input) => {
+    const fallback = await input
+        .request("shutdown_document")
+        .catch(() => err(new HopperProcessError(null)));
+    const confirmed = fallback.ok && isHopperShutdownAcknowledgement(fallback.value);
+    if (!confirmed)
+        input.logger.warn({ status: fallback.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown fallback was not confirmed");
+    return confirmed;
+};
+const stopProcess = async (input, state) => {
+    const supervisor = input.processSupervisor;
+    if (supervisor === undefined)
+        return;
+    const stopped = await supervisor.stop(state.cleanupResult === undefined
+        ? {}
+        : { cleanupResult: state.cleanupResult });
+    const diagnostic = createOwnedHopperShutdownDiagnostic(supervisor.launch, stopped, state.cleanupResult);
+    try {
+        input.onDiagnostic?.(diagnostic);
+    }
+    catch {
+        // Diagnostic consumers cannot change the already-observed cleanup result.
+    }
+    input.logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
+    if (stopped.status !== "incomplete") {
+        state.ownedProcessStopped = stopped.status !== "not-owned";
+        return;
+    }
+    const processGroupId = supervisor.launch.ownership?.processGroupId;
+    const resource = processGroupId === undefined
+        ? "hopper-process"
+        : `process-group:${String(processGroupId)}`;
+    state.resources.add(resource);
+    state.issues.push({ resource, reason: stopped.reason });
+    input.logger.warn({ reason: stopped.reason }, "Owned launcher cleanup failed closed");
+};
+const recordUnconfirmedDocument = (input, state) => {
+    if ((input.socket === undefined && input.launch === undefined) ||
+        state.shutdownConfirmed ||
+        state.ownedProcessStopped)
+        return;
+    state.resources.add("hopper-document");
+    state.issues.push({
+        resource: "hopper-document",
+        reason: input.activeRequest === null
+            ? "authenticated shutdown acknowledgement was not observed"
+            : `bridge operation ${input.activeRequest.operation} remained active after caller ${input.activeRequest.callerState}`,
+    });
+};
+const closeRuntimeRoot = async (runtimeRoot, state) => {
+    try {
+        await runtimeRoot?.close();
+    }
+    catch (cause) {
+        const resource = runtimeRoot?.path ?? "hopper-runtime-root";
+        state.resources.add(resource);
+        state.issues.push({
+            resource,
+            reason: cause instanceof Error
+                ? cause.message
+                : "private runtime root cleanup failed",
+        });
+    }
+};
+const cleanupOutcome = (input, state) => {
+    if (state.issues.length === 0)
+        return ok(null);
+    return err(new ProviderCleanupError("hopper", [...state.resources], {
+        issues: cleanupIssueDetails(state.issues),
+        ...(input.runtimeRoot === undefined
+            ? {}
+            : { runtime_root: input.runtimeRoot.path }),
+        ...(input.activeRequest === null
+            ? {}
+            : { active_request: activityDetails(input.activeRequest) }),
+    }));
+};
+const cleanupIssueDetails = (issues) => issues.map((issue) => ({
+    resource: issue.resource,
+    reason: issue.reason,
+}));
+const activityDetails = (activity) => ({
+    request_id: activity.requestId,
+    operation: activity.operation,
+    elapsed_ms: activity.elapsedMs,
+    timeout_ms: activity.timeoutMs,
+    caller_state: activity.callerState,
+    queued_requests: activity.queuedRequests,
+});
+const report = async (progress, completed, message) => {
+    await progress
+        ?.report({
+        phase: "hopper_cleanup",
+        completed,
+        total: 1,
+        message,
+    })
+        .catch(() => undefined);
+};