rea-agents 4.1.0 → 6.0.0

package/dist/contracts/webNetworkCaptureToolContracts.js

@@ -0,0 +1,24 @@
+import { inspectWebNetworkCaptureInputSchema, webNetworkCaptureSchema, } from "../domain/webNetworkCapture.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+/** Historical inspection is distinct from live browser capture and runtime authority. */
+export const WEB_NETWORK_CAPTURE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_web_network_capture",
+        ...toolContractMetadata("inspect_web_network_capture"),
+        description: "Inspect retained local HAR 1.2 or native mitmproxy capture records without contacting recorded URLs. Returns original ordinals, pointers/byte ranges, preserved producer fields, precise numeric representations and exact exposed binary bytes inline. Excludes known transport credentials and explicitly marked values. Decodes every record before optional ordinal selection; malformed or oversized captures return no partial success. Duplicate HAR members are invalid; prototype-named __proto__ members are unsupported by the current shared JSON boundary. Uses pinned upstream parsers, owned temporary files and bounded offline processes. Native mitmproxy requires caller-supplied mitmdump 12.2.3 on Linux. Browser transaction IDs, runtime attribution and original bytes of HAR Unicode text remain unknown.",
+        kind: "browser-provider",
+        inputSchema: inspectWebNetworkCaptureInputSchema,
+        outputSchema: evidenceResultOf(webNetworkCaptureSchema),
+        examples: [
+            {
+                title: "Inspect historical HAR entries",
+                input: {
+                    capture_path: "/captures/session.har",
+                    format: "har",
+                    record_ordinals: [0, 2],
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/webRuntimeToolContracts.js

@@ -0,0 +1,43 @@
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
+import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
+/** Native website runtime primitives distinguish instrumentation from listener inspection. */
+export const WEB_RUNTIME_TOOL_CONTRACTS = [
+    {
+        name: "observe_web_execution",
+        ...toolContractMetadata("observe_web_execution"),
+        description: "Instrument one selected CDP page for a finite, externally driven precise coverage window. Resets execution counters and prevents optimized execution until stopped. Returns complete nested UTF-16 ranges/counts, independently hashed script text and request initiator associations by session script ID. Does not navigate, click, evaluate selected code or close the externally owned page. Navigation ends document-scoped collection; workers and UI causality remain outside this claim. Emits an actual armed progress notification before external actions.",
+        kind: "browser-provider",
+        inputSchema: observeWebExecutionInputSchema,
+        outputSchema: evidenceResultOf(webExecutionSchema),
+        examples: [
+            {
+                title: "Attribute externally triggered page execution",
+                input: {
+                    cdp_endpoint: "http://127.0.0.1:9222",
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    observation_ms: 10_000,
+                },
+            },
+        ],
+    },
+    {
+        name: "inspect_web_event_listeners",
+        ...toolContractMetadata("inspect_web_event_listeners"),
+        description: "Inspect listeners registered directly on the first main-document CSS match in one selected CDP page. Returns event flags, native callback locations, source ownership and exact script text/digests inline. Does not dispatch events, evaluate JavaScript or invoke handlers. Delegated ancestor/framework listeners and execution history remain unknown. Releases REA's object group and transport, preserving the external page.",
+        kind: "browser-provider",
+        inputSchema: inspectWebEventListenersInputSchema,
+        outputSchema: evidenceResultOf(webEventListenersSchema),
+        examples: [
+            {
+                title: "Find a selected button's callback source",
+                input: {
+                    cdp_endpoint: "http://127.0.0.1:9222",
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    selector: "#submit",
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/webScriptToolContracts.js

@@ -0,0 +1,68 @@
+import { exportWebScriptsInputSchema, webScriptExportResultSchema, } from "../domain/webScriptExport.js";
+import { webModuleTraceInputSchema, webModuleTraceResultSchema, } from "../domain/webModuleTrace.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { webSourceLocationInputSchema, webSourceLocationResultSchema, } from "../domain/webSourceLocation.js";
+/** Local captured-script publication contracts shared by CLI and MCP. */
+export const WEB_SCRIPT_TOOL_CONTRACTS = [
+    {
+        name: "trace_web_source_location",
+        ...toolContractMetadata("trace_web_source_location"),
+        description: "Trace one generated position in an exported website script through an explicitly paired local source map. Verifies manifest, selected script and map SHA-256/byte identities; returns every equal-position mapping, reported source/root, resolved source URL, embedded sourcesContent and original position inline. One-based lines and zero-based UTF-16 columns; greatest generated position <= requested across lines. Duplicate sources and generated-only mappings remain distinct. Caller-selected pairing does not establish deployment authenticity or execution. Regular maps and inline indexed sections only; external section URLs are unsupported. No network access or application execution; uses the pinned upstream codec in an owned Node process with private temporary files, independent 192 MiB old-generation heap and 20-second deadline. 4 MiB map, 32 MiB reply; complete evidence or actionable resource failure. Cleanup may extend the deadline.",
+        kind: "application",
+        inputSchema: webSourceLocationInputSchema,
+        outputSchema: evidenceResultOf(webSourceLocationResultSchema),
+        examples: [
+            {
+                title: "Trace a selected captured JavaScript point to embedded original source",
+                input: {
+                    manifest_path: "/analysis/scripts/manifest.json",
+                    script_index: 0,
+                    source_map: {
+                        path: "/analysis/app.js.map",
+                        url: "https://example.test/app.js.map",
+                    },
+                    generated_position: { line: 1, column: 25 },
+                },
+            },
+        ],
+    },
+    {
+        name: "trace_web_module_imports",
+        ...toolContractMetadata("trace_web_module_imports"),
+        description: "Trace one exported website script's outgoing native ES imports/re-exports, using exact URL and optional selected import-map context. Reads a local export_web_scripts manifest and verifies the selected source's SHA-256/size; returns source positions, native resolved URLs or exact errors, every matching captured candidate and explicit unknown execution. Query/fragment identities are preserved. Computed imports and bundler IDs remain unknown. Select importer_url for unknown inline/document-base context. Caller-supplied Chromium executes only a trusted REA resolver stub in an owned context with page requests locally fulfilled/blocked; no captured application execution or asset refetch. Requires absolute REA_BROWSER_EXECUTABLE for literal imports. 32 MiB manifest, 16 MiB source, 4 MiB map and 20-second native deadline; cleanup may extend the deadline.",
+        kind: "application",
+        inputSchema: webModuleTraceInputSchema,
+        outputSchema: evidenceResultOf(webModuleTraceResultSchema),
+        examples: [
+            {
+                title: "Trace an exported module under a selected import map",
+                input: {
+                    manifest_path: "/analysis/exported-scripts/manifest.json",
+                    script_index: 0,
+                    import_map: {
+                        path: "/analysis/import-map.json",
+                        base_url: "https://example.test/app/",
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: "export_web_scripts",
+        ...toolContractMetadata("export_web_scripts"),
+        description: "Export JavaScript bytes already retained in one local inspect_web_page or capture_browser_scenario JSON capture (normalized result or complete Evidence). Writes scripts and a digest-verified manifest into an absent absolute output_directory. Returns all source URLs, script or transaction/event references, unavailable states, and an analysis_input for analyze_javascript_application when any bytes were exported. Include script sources in inspect_web_page or select capture.network.response_body in scenarios. No refetch or execution. Safe unambiguous URL layouts preserve relative module paths; versions, query variants, inline scripts, and path collisions are isolated with explicit resolution limitations.",
+        kind: "application",
+        inputSchema: exportWebScriptsInputSchema,
+        outputSchema: evidenceResultOf(webScriptExportResultSchema),
+        examples: [
+            {
+                title: "Export a saved website capture for static JavaScript analysis",
+                input: {
+                    capture_path: "/analysis/capture.json",
+                    output_directory: "/analysis/exported-scripts",
+                },
+            },
+        ],
+    },
+];

package/dist/domain/analysisErrorBase.js

@@ -2,10 +2,14 @@
 const ANALYSIS_ERROR_TAGS = [
     "AnalysisProtocolError",
     "AnalysisInputError",
+    "AnalysisAccessDeniedError",
+    "AnalysisArtifactChangedError",
     "AnalysisOutputError",
     "AnalysisCapabilityUnavailableError",
+    "AnalysisUnsupportedTargetError",
     "AnalysisCancelledError",
     "AnalysisTimeoutError",
+    "AnalysisResourceConstraintError",
     "ProviderSelectionError",
     "ProviderAdapterError",
     "BrowserObservationError",
@@ -26,8 +30,19 @@ const ANALYSIS_ERROR_TAGS = [
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
+    capturedOutput;
+    constructor(message, options) {
+        super(message, options);
+        this.capturedOutput =
+            options?.capturedOutput === undefined
+                ? undefined
+                : { ...options.capturedOutput };
+    }
     userMessage = undefined;
     userCategory = undefined;
     cleanupIncomplete = false;
     cleanupResources = [];
+    executionFailure = undefined;
+    partialObservation = undefined;
+    cleanupReport = undefined;
 }

package/dist/domain/analysisErrorCore.js

@@ -1,4 +1,32 @@
-import { AnalysisError } from "./analysisErrorBase.js";
+import { AnalysisError, } from "./analysisErrorBase.js";
+/** A readable supplied artifact lies outside this operation's supported target formats. */
+export class AnalysisUnsupportedTargetError extends AnalysisError {
+    operation;
+    path;
+    reason;
+    _tag = "AnalysisUnsupportedTargetError";
+    constructor(operation, path, reason, options) {
+        super(`Unsupported target for ${operation} at ${path}: ${reason}`, options);
+        this.operation = operation;
+        this.path = path;
+        this.reason = reason;
+    }
+}
+/** Provider reported a resource failure, distinct from malformed input or unsupported coverage. */
+export class AnalysisResourceConstraintError extends AnalysisError {
+    operation;
+    resource;
+    reason;
+    reportedLimits;
+    _tag = "AnalysisResourceConstraintError";
+    constructor(operation, resource, reason, reportedLimits, options) {
+        super(`Resource constraint during ${operation}: ${reason}`, options);
+        this.operation = operation;
+        this.resource = resource;
+        this.reason = reason;
+        this.reportedLimits = reportedLimits;
+    }
+}
 /** Provider-neutral invalid analysis input or output at an application boundary. */
 export class AnalysisProtocolError extends AnalysisError {
     _tag = "AnalysisProtocolError";
@@ -31,19 +59,21 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError {
     operation;
     reason;
     _tag = "AnalysisCapabilityUnavailableError";
-    constructor(providerId, operation, reason) {
-        super(`Provider ${providerId} cannot execute ${operation}: ${reason}`);
+    userMessage;
+    constructor(providerId, operation, reason, options) {
+        super(`Provider ${providerId} cannot execute ${operation}: ${reason}`, options);
         this.providerId = providerId;
         this.operation = operation;
         this.reason = reason;
+        this.userMessage = options?.userMessage;
     }
 }
 /** Caller cancellation won before provider-neutral work completed. */
 export class AnalysisCancelledError extends AnalysisError {
     operation;
     _tag = "AnalysisCancelledError";
-    constructor(operation) {
-        super(`Analysis operation was cancelled: ${operation}`);
+    constructor(operation, options) {
+        super(`Analysis operation was cancelled: ${operation}`, options);
         this.operation = operation;
     }
 }
@@ -52,9 +82,35 @@ export class AnalysisTimeoutError extends AnalysisError {
     operation;
     timeoutMs;
     _tag = "AnalysisTimeoutError";
-    constructor(operation, timeoutMs) {
-        super(`Analysis operation timed out after ${String(timeoutMs)}ms: ${operation}`);
+    constructor(operation, timeoutMs, options) {
+        super(`Analysis operation timed out after ${String(timeoutMs)}ms: ${operation}`, options);
         this.operation = operation;
         this.timeoutMs = timeoutMs;
     }
 }
+/** Host filesystem permissions denied the selected read; this is not malformed caller input. */
+export class AnalysisAccessDeniedError extends AnalysisError {
+    operation;
+    path;
+    systemCode;
+    _tag = "AnalysisAccessDeniedError";
+    constructor(operation, path, systemCode, options) {
+        super(`Host filesystem read access denied (${systemCode}) for ${path} during ${operation}`, options);
+        this.operation = operation;
+        this.path = path;
+        this.systemCode = systemCode;
+    }
+}
+/** Selected artifact acquisition observed a change, so no stable identity can be reported. */
+export class AnalysisArtifactChangedError extends AnalysisError {
+    operation;
+    path;
+    reason;
+    _tag = "AnalysisArtifactChangedError";
+    constructor(operation, path, reason, options) {
+        super(`Selected artifact changed during acquisition: ${reason}`, options);
+        this.operation = operation;
+        this.path = path;
+        this.reason = reason;
+    }
+}

package/dist/domain/analysisErrorPresentation.js

@@ -1,4 +1,4 @@
-import { AnalysisInputError } from "./analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisUnsupportedTargetError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { ArtifactOperationError } from "./artifactOperationError.js";
 import { BinaryTargetError, ConfigurationError, NoBinaryOpenError, } from "./configurationErrors.js";
 import { BrowserObservationError } from "./browserObservationError.js";
@@ -9,6 +9,14 @@ import { UnknownRegistryError } from "./unknownRegistryError.js";
 import {} from "./analysisErrorBase.js";
 import {} from "./analysisErrorProjection.js";
 export const analysisErrorRemediationAction = (error) => {
+    if (error instanceof AnalysisUnsupportedTargetError)
+        return "Select a target supported by this operation or choose an operation supporting the reported target format.";
+    if (error instanceof AnalysisResourceConstraintError)
+        return error.resource === "cpu"
+            ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
+            : error.resource === "file-size"
+                ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."
+                : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.";
     if (error instanceof HopperTimeoutError)
         return error.providerState === "busy"
             ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
@@ -26,6 +34,10 @@ export const analysisErrorRemediationAction = (error) => {
     if (error instanceof BinaryTargetError &&
         error.constraint === "directory_requires_file")
         return "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path or run `rea analyze <directory>`. For binary analysis, select its executable file.";
+    if (error instanceof AnalysisAccessDeniedError)
+        return "Check the current process's read access to the selected path. Retry with a readable local file.";
+    if (error instanceof AnalysisArtifactChangedError)
+        return "Wait until the selected file is stable, then retry this operation.";
     if (error instanceof AnalysisInputError)
         return "Correct the listed arguments and retry.";
     if (error instanceof UnknownRegistryError && error.reason === "not-found")
@@ -73,17 +85,29 @@ const artifactErrorCategory = (reason) => {
 };
 const STATIC_ERROR_CATEGORIES = {
     AnalysisInputError: "invalid_input",
+    AnalysisAccessDeniedError: "unavailable",
+    AnalysisArtifactChangedError: "integrity_mismatch",
     AnalysisCapabilityUnavailableError: "unsupported_provider",
+    AnalysisUnsupportedTargetError: "unsupported_target",
     ProviderSelectionError: "unsupported_provider",
     EvidenceIntegrityError: "integrity_mismatch",
     AnalysisCancelledError: "cancelled",
     HopperCancelledError: "cancelled",
     AnalysisTimeoutError: "timeout",
+    AnalysisResourceConstraintError: "resource_constraint",
     HopperTimeoutError: "timeout",
     NoBinaryOpenError: "unavailable",
     BinaryTargetError: "unavailable",
 };
 export const analysisErrorUserMessage = (error) => {
+    if (error instanceof AnalysisUnsupportedTargetError)
+        return error.message;
+    if (error instanceof AnalysisResourceConstraintError)
+        return error.reason;
+    if (error instanceof AnalysisAccessDeniedError)
+        return "Host filesystem permissions denied read access to the selected path.";
+    if (error instanceof AnalysisArtifactChangedError)
+        return "The selected artifact changed during acquisition; no stable snapshot was decoded.";
     if (error instanceof AnalysisInputError)
         return "Analysis input is invalid. Check the arguments and try again.";
     const hopperMessage = hopperErrorUserMessage(error);
@@ -202,10 +226,14 @@ const evidenceFileMessage = (reason) => {
 const KNOWN_ERROR_TAGS = {
     AnalysisProtocolError: true,
     AnalysisInputError: true,
+    AnalysisAccessDeniedError: true,
+    AnalysisArtifactChangedError: true,
     AnalysisOutputError: true,
     AnalysisCapabilityUnavailableError: true,
+    AnalysisUnsupportedTargetError: true,
     AnalysisCancelledError: true,
     AnalysisTimeoutError: true,
+    AnalysisResourceConstraintError: true,
     ProviderSelectionError: true,
     ProviderAdapterError: true,
     BrowserObservationError: true,

package/dist/domain/analysisErrorProjection.js

@@ -1,5 +1,6 @@
+import { jsonValueSchema } from "./jsonValue.js";
 import { analysisErrorCategory, analysisErrorRemediationAction, analysisErrorUserMessage, assertKnownAnalysisErrorTag, } from "./analysisErrorPresentation.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "./analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { ArtifactOperationError } from "./artifactOperationError.js";
 import { BinaryTargetError } from "./configurationErrors.js";
 import { BrowserObservationError } from "./browserObservationError.js";
@@ -13,7 +14,10 @@ import {} from "./analysisErrorBase.js";
 export const projectAnalysisError = (error) => {
     assertKnownAnalysisErrorTag(error._tag);
     const code = errorCode(error);
-    const details = errorDetails(error);
+    const primaryDetails = errorDetails(error);
+    const details = error.capturedOutput === undefined
+        ? primaryDetails
+        : { ...primaryDetails, captured_output: { ...error.capturedOutput } };
     return {
         code,
         category: analysisErrorCategory(error),
@@ -88,10 +92,14 @@ const STATIC_ERROR_CODES = {
     AnalysisOutputError: "unreadable_output",
     HopperProtocolError: "unreadable_output",
     AnalysisInputError: "invalid_request",
+    AnalysisAccessDeniedError: "access_denied",
+    AnalysisArtifactChangedError: "artifact_changed",
     AnalysisCapabilityUnavailableError: "capability_unavailable",
+    AnalysisUnsupportedTargetError: "unsupported_target",
     AnalysisCancelledError: "cancelled",
     HopperCancelledError: "cancelled",
     AnalysisTimeoutError: "provider_timeout",
+    AnalysisResourceConstraintError: "resource_constraint",
     HopperTimeoutError: "provider_timeout",
     HopperProcessError: "provider_unavailable",
     HopperStartError: "provider_unavailable",
@@ -120,6 +128,33 @@ const errorDetails = (error) => requestErrorDetails(error) ??
     providerErrorDetails(error) ??
     lifecycleErrorDetails(error);
 const requestErrorDetails = (error) => {
+    if (error instanceof AnalysisUnsupportedTargetError)
+        return {
+            operation: error.operation,
+            path: error.path,
+            reason: error.reason,
+        };
+    if (error instanceof AnalysisResourceConstraintError)
+        return {
+            operation: error.operation,
+            resource: error.resource,
+            reason: error.reason,
+            reported_limits: error.reportedLimits,
+        };
+    if (error instanceof AnalysisArtifactChangedError)
+        return {
+            operation: error.operation,
+            path: error.path,
+            reason: error.reason,
+            boundary: "stable-artifact-read",
+        };
+    if (error instanceof AnalysisAccessDeniedError)
+        return {
+            operation: error.operation,
+            path: error.path,
+            system_code: error.systemCode,
+            boundary: "filesystem-read",
+        };
     if (error instanceof AnalysisOutputError)
         return { operation: error.operation, reason: error.reason };
     if (error instanceof AnalysisInputError && error.issues.length > 0)
@@ -156,6 +191,7 @@ const artifactStateErrorDetails = (error) => {
             operation: error.operation,
             reason: error.reason,
             ...(error.reason === "limit" ? { truncated: true } : {}),
+            ...(error.detail === undefined ? {} : { detail: error.detail }),
         };
     if (error instanceof UnknownRegistryError)
         return { reason: error.reason };
@@ -271,10 +307,24 @@ const lifecycleErrorDetails = (error) => {
         return {
             cleanup: "incomplete",
             resources: [...error.cleanupResources],
+            ...(error.cleanupReport === undefined
+                ? {}
+                : { cleanup_report: jsonValueSchema.parse(error.cleanupReport) }),
+            ...(error.executionFailure === undefined
+                ? {}
+                : { execution_failure: error.executionFailure }),
+            ...(error.partialObservation === undefined
+                ? {}
+                : {
+                    partial_observation: jsonValueSchema.parse(error.partialObservation),
+                }),
         };
     if (error._tag === "ProcessCaptureError" &&
         error.userCategory === "cancelled")
         return { operation: "process_capture", cleanup: "complete" };
+    if (error._tag === "ProcessCaptureError" &&
+        error.executionFailure !== undefined)
+        return { execution_failure: error.executionFailure };
     if (error instanceof BinaryTargetError)
         return {
             path: error.path,
@@ -286,6 +336,7 @@ const lifecycleErrorDetails = (error) => {
     return undefined;
 };
 const RETRYABLE_CODES = new Set([
+    "artifact_changed",
     "invalid_request",
     "provider_timeout",
     "cancelled",