rea-agents 2.4.0 → 3.0.0

package/dist/contracts/toolEffects.js

@@ -38,6 +38,9 @@ export const TOOL_EFFECTS = {
     procedure_callees: evidence,
     procedure_callers: evidence,
     procedure_info: evidence,
+    read_function_instructions: evidence,
+    read_bytes: evidence,
+    address_to_file_offset: evidence,
     procedure_references: evidence,
     procedure_pseudo_code: evidence,
     resolve_containing_procedure: evidence,
@@ -64,13 +67,17 @@ export const TOOL_EFFECTS = {
     find_xrefs_to_name: evidence,
     binary_overview: evidence,
     analyze_function: evidence,
+    inspect_native_api: effects({ mutatesSession: true, idempotent: false }),
     trace_feature: effects({ mutatesSession: true, idempotent: false }),
+    find_code_for_string: effects({ mutatesSession: true, idempotent: false }),
+    trace_call_path: effects({ mutatesSession: true, idempotent: false }),
     inspect_macho: nativeEvidence,
     inspect_signature: nativeEvidence,
     inspect_plist: nativeEvidence,
     list_architectures: nativeEvidence,
     demangle_swift: nativeEvidence,
     inventory_artifact: evidence,
+    inspect_artifact: evidence,
     extract_artifact: effects({ mutatesSession: true, writesFilesystem: true }),
     inspect_managed_artifact: evidence,
     inspect_managed_members: evidence,
@@ -88,14 +95,29 @@ export const TOOL_EFFECTS = {
     compare_web_captures: browserEvidence,
     capture_web_screenshot: browserEvidence,
     compare_web_screenshots: browserEvidence,
+    capture_browser_scenario: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        changesUiState: true,
+        mayDiscardData: true,
+        idempotent: false,
+    }),
     list_electron_targets: browserEvidence,
     inspect_electron_page: browserEvidence,
+    list_javascript_runtime_targets: browserEvidence,
+    observe_javascript_runtime: browserEvidence,
     analyze_javascript_application: evidence,
     reconcile_javascript_runtime: evidence,
     trace_application_feature: evidence,
     trace_javascript_semantics: evidence,
     compare_application_versions: evidence,
+    compare_source_to_bundle: evidence,
     compare_javascript_export_shapes: evidence,
+    build_reconstruction_obligation_ledger: evidence,
+    evaluate_reconstruction_readiness: evidence,
     run_replay_machine: effects(),
     run_controlled_replay: effects({
         mutatesSession: true,
@@ -128,6 +150,9 @@ export const TOOL_EFFECTS = {
         writesFilesystem: true,
         mayDiscardData: true,
     }),
+    snapshot_evidence_bundle: effects({ mutatesSession: true }),
+    get_navigation_context: effects({ mutatesSession: true }),
+    inspect_address_context: effects({ mutatesSession: true }),
     import_evidence_bundle: effects({ mutatesSession: true }),
     capture_process_scenario: effects({
         mutatesSession: true,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
-import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
 import { residualUnknownSchema } from "../domain/residualUnknown.js";
-import { referenceKindSchema } from "../domain/hopperValues.js";
+import { functionInstructionWindowSchema, referenceKindSchema, } from "../domain/hopperValues.js";
+import { nativeApiInspectionResultSchema } from "../domain/nativeApiBoundary.js";
 import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
 import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
 import { managedMemberComparisonResultSchema } from "../domain/managedMemberComparison.js";
 import { managedNativeVerificationResultSchema } from "../domain/managedNativeVerification.js";
@@ -20,7 +22,15 @@ import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCor
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
 import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { addressList, addressedEntry, bounded, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+import { addressList, analysisActivity, addressedEntry, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+const contextFacetSchema = z.discriminatedUnion("state", [
+    z.object({ state: z.literal("available"), value: jsonValueSchema }),
+    z.object({
+        state: z.literal("unavailable"),
+        reason: z.string(),
+        remediation: z.string(),
+    }),
+]);
 /** Exact structured-content schemas shared by direct analysis providers. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -43,6 +53,18 @@ export const officialOutputSchemas = {
     procedure_callees: resultOf(addressList),
     procedure_callers: resultOf(addressList),
     procedure_info: procedureInfoOutput,
+    read_function_instructions: resultOf(functionInstructionWindowSchema),
+    read_bytes: resultOf(z.object({
+        address: z.string(),
+        requested_bytes: z.number().int().min(1).max(4_096),
+        returned_bytes: z.number().int().min(0).max(4_096),
+        bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u),
+        complete: z.boolean(),
+    })),
+    address_to_file_offset: resultOf(z.object({
+        address: z.string(),
+        file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    })),
     procedure_references: resultOf(z.object({
         procedure: procedureIdentity,
         direction: z.enum(["incoming", "outgoing"]),
@@ -69,6 +91,55 @@ export const officialOutputSchemas = {
     unset_bookmark: resultOf(z.boolean()),
     xrefs: resultOf(addressList),
 };
+const literalTraceOutput = resultOf(z.object({
+    query: z.string(),
+    search_mode: z.literal("literal"),
+    operations_used: z.number().int().min(0),
+    operation_budget: z.number().int().min(1),
+    matches: z.array(z.object({
+        type: z.enum(["string", "procedure"]),
+        address: z.string(),
+        value: z.string(),
+    })),
+    references: z.array(z.object({
+        target_address: z.string(),
+        source_address: z.string(),
+        containing_procedure: containingProcedureResolution,
+    })),
+    truncated: z.boolean(),
+    residual_unknowns: z.array(z.string()),
+}));
+const callPathTraceOutput = resultOf(z.object({
+    start: z.string(),
+    goal: z.string().nullable(),
+    direction: z.enum(["forward", "backward"]),
+    goal_status: z.enum(["not_requested", "reached", "not_reached"]),
+    nodes: z.array(z.object({
+        address: z.string(),
+        depth: z.number().int().min(0),
+    })),
+    edges: z.array(z.object({
+        source_address: z.string(),
+        target_address: z.string(),
+        discovery_depth: z.number().int().min(1),
+    })),
+    traversal_path: z.array(z.string()),
+    failures: z.array(z.object({
+        address: z.string(),
+        error: analysisErrorProjectionSchema,
+    })),
+    frontier: z.array(z.string()),
+    limits: z.object({
+        max_depth: z.number().int().min(1),
+        max_nodes: z.number().int().min(1),
+        max_operations: z.number().int().min(1),
+        nodes_visited: z.number().int().min(1),
+        operations_used: z.number().int().min(0),
+    }),
+    truncated: z.boolean(),
+    residual_unknowns: z.array(z.string()),
+    limitations: z.array(z.string()),
+}));
 /** Exact structured-content schemas for composed analysis workflows. */
 export const enhancedOutputSchemas = {
     swift_classes: symbolDiscoveryOutput("classes"),
@@ -126,24 +197,10 @@ export const enhancedOutputSchemas = {
         string_count: z.number().int().min(0),
     })),
     analyze_function: functionDossierOutput,
-    trace_feature: resultOf(z.object({
-        query: z.string(),
-        search_mode: z.literal("literal"),
-        operations_used: z.number().int().min(0),
-        operation_budget: z.number().int().min(1),
-        matches: z.array(z.object({
-            type: z.enum(["string", "procedure"]),
-            address: z.string(),
-            value: z.string(),
-        })),
-        references: z.array(z.object({
-            target_address: z.string(),
-            source_address: z.string(),
-            containing_procedure: containingProcedureResolution,
-        })),
-        truncated: z.boolean(),
-        residual_unknowns: z.array(z.string()),
-    })),
+    inspect_native_api: resultOf(nativeApiInspectionResultSchema),
+    trace_feature: literalTraceOutput,
+    find_code_for_string: literalTraceOutput,
+    trace_call_path: callPathTraceOutput,
 };
 /** Exact Evidence v2 schemas for provider-neutral native inspection. */
 export const nativeOutputSchemas = {
@@ -156,6 +213,7 @@ export const nativeOutputSchemas = {
 /** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
 export const artifactOutputSchemas = {
     inventory_artifact: resultOf(artifactInventoryResultSchema),
+    inspect_artifact: resultOf(artifactInspectionResultSchema),
     extract_artifact: resultOf(artifactExtractionResultSchema),
 };
 /** Exact Evidence v2 schema for execution-free managed static analysis. */
@@ -210,6 +268,7 @@ export const sessionOutputSchemas = {
                 reasons: z.array(z.string()),
                 remediation: z.string().nullable(),
             }),
+            analysis_activity: analysisActivity,
             recommended_actions: z.array(z.string()),
         }),
         z.object({
@@ -226,6 +285,7 @@ export const sessionOutputSchemas = {
                 next_cursor: z.number().int().min(0).nullable(),
                 has_more: z.boolean(),
             }),
+            client_features: clientFeatureAvailabilitySchema,
         }),
         z.union([
             sessionProvider.extend({
@@ -243,14 +303,34 @@ export const sessionOutputSchemas = {
             }),
         ]),
     ])),
-    export_evidence_bundle: lifecycleResultOf(z.union([
-        evidenceBundleSchema,
-        z.object({
-            path: z.string(),
-            bytes: z.number().int().min(0),
-            records: z.number().int().min(0),
-        }),
-    ])),
+    export_evidence_bundle: lifecycleResultOf(z.object({
+        path: z.string(),
+        bytes: z.number().int().min(0),
+        records: z.number().int().min(0),
+        unknowns: z.number().int().min(0),
+    })),
+    snapshot_evidence_bundle: lifecycleResultOf(z.object({
+        bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+        bundle_version: z.literal(2),
+        bytes: z.number().int().min(0),
+        records: z.number().int().min(0),
+        unknowns: z.number().int().min(0),
+        bundle_uri: z.string().regex(/^rea:\/\/evidence-bundle\/[a-f0-9]{64}$/u),
+    })),
+    get_navigation_context: lifecycleResultOf(z.object({
+        document: z.string(),
+        address: z.string(),
+        procedure: z.union([z.string(), z.null()]),
+    })),
+    inspect_address_context: lifecycleResultOf(z.object({
+        address: z.string(),
+        document: z.string().nullable(),
+        name: contextFacetSchema,
+        procedure: contextFacetSchema,
+        comment: contextFacetSchema,
+        inline_comment: contextFacetSchema,
+        bookmarks: contextFacetSchema,
+    })),
     import_evidence_bundle: lifecycleResultOf(z.object({
         imported: z.number().int().min(0),
         total: z.number().int().min(0),
@@ -264,7 +344,17 @@ export const sessionOutputSchemas = {
     build_call_path: resultOf(callPathResultSchema),
     correlate_static_and_runtime: resultOf(staticRuntimeCorrelationResultSchema),
     verify_reconstruction: resultOf(reconstructionVerificationResultSchema),
-    list_unknowns: lifecycleResultOf(z.array(residualUnknownSchema)),
+    list_unknowns: lifecycleResultOf(z.object({
+        items: z.array(z.object({
+            unknown: residualUnknownSchema,
+            uri: z.string().regex(/^rea:\/\/unknown\/unk_[a-f0-9]{64}$/u),
+        })),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(500),
+        total: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+        has_more: z.boolean(),
+    })),
     record_unknown: lifecycleResultOf(residualUnknownSchema),
     update_unknown: lifecycleResultOf(residualUnknownSchema),
     verify_unknown_resolution: lifecycleResultOf(z.object({

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -111,6 +111,22 @@ const analysisRun = z
     ]),
 })
     .nullable();
+export const analysisActivity = z.object({
+    status: z.enum(["not_observed", "idle", "busy", "timed_out_busy"]),
+    providers: z.array(z.object({
+        provider: providerIdentity,
+        active: z
+            .object({
+            request_id: z.number().int().min(1),
+            operation: z.string().min(1),
+            elapsed_ms: z.number().int().min(0),
+            timeout_ms: z.number().int().min(0),
+            caller_state: z.enum(["waiting", "timed_out", "cancelled"]),
+        })
+            .nullable(),
+        queued_requests: z.number().int().min(0),
+    })),
+});
 const providerRejectionCode = z.enum(PROVIDER_REJECTION_CODES);
 const providerDiagnostics = z.record(z.string(), z.json());
 const providerAvailability = z.discriminatedUnion("status", [
@@ -153,12 +169,26 @@ const providerTargetSupport = z.discriminatedUnion("status", [
         diagnostics: providerDiagnostics,
     }),
 ]);
+const clientFeatureNameSchema = z.enum([
+    "elicitation_form",
+    "elicitation_url",
+    "roots",
+    "sampling",
+]);
+/** Negotiated MCP client features that affect REA workflow availability. */
+export const clientFeatureAvailabilitySchema = z.object({
+    elicitation_form: z.boolean(),
+    elicitation_url: z.boolean(),
+    roots: z.boolean(),
+    sampling: z.boolean(),
+});
 export const toolAvailability = z.object({
     name: z.string(),
     surface: z.string(),
     available: z.boolean(),
     reason: z.enum([
         "available",
+        "client_capability_missing",
         "target_required",
         "provider_missing",
         "provider_unavailable",
@@ -167,6 +197,12 @@ export const toolAvailability = z.object({
         "policy_disabled",
     ]),
     remediation: z.string().nullable(),
+    client_requirements: z.object({
+        required: z.array(clientFeatureNameSchema),
+        optional: z.array(clientFeatureNameSchema),
+        missing_required: z.array(clientFeatureNameSchema),
+        missing_optional: z.array(clientFeatureNameSchema),
+    }),
     effects: z.strictObject({
         mutatesTarget: z.boolean(),
         mutatesSession: z.boolean(),
@@ -189,6 +225,7 @@ export const sessionProvider = z.object({
     providers: z.array(providerIdentity),
     capabilities: z.array(providerCapability),
     analysis_run: analysisRun,
+    analysis_activity: analysisActivity,
     analysis_provider_binding: z
         .object({
         provider: providerIdentity,

package/dist/domain/analysisErrorPresentation.js

@@ -2,6 +2,8 @@ import { AnalysisInputError, ArtifactOperationError, BinaryTargetError, BrowserO
 export const analysisErrorRemediationAction = (error) => {
     if (error instanceof AnalysisInputError)
         return "Correct the listed arguments and retry.";
+    if (error instanceof UnknownRegistryError && error.reason === "not-found")
+        return "Check that the unknown_id belongs to this session, then retry.";
     if (error instanceof ReplayPlanStaleError)
         return "Review the rebuilt replay plan and explicitly approve its new digest.";
     if (error instanceof PermissionRequiredError)
@@ -64,7 +66,7 @@ const artifactErrorCategory = (reason) => {
         return "truncated";
     if (reason === "cancelled")
         return "cancelled";
-    if (reason === "unavailable")
+    if (reason === "policy" || reason === "unavailable")
         return "unavailable";
     return "execution_failure";
 };
@@ -103,6 +105,8 @@ export const analysisErrorUserMessage = (error) => {
         return evidenceFileMessage(error.reason);
     if (error instanceof InvestigationWorkspaceError)
         return investigationWorkspaceMessage(error.reason);
+    if (error instanceof UnknownRegistryError && error.reason === "not-found")
+        return "The requested residual unknown does not exist in this session. Check the unknown_id and try again.";
     if (error instanceof UnknownRegistryError)
         return "Evidence state changed before the update completed. Refresh the current state and try again.";
     if (error instanceof ConfigurationError)
@@ -163,8 +167,10 @@ const artifactMessage = (reason) => {
         return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
     if (reason === "path")
         return "Artifact path is not allowed. Choose a path inside the artifact and try again.";
+    if (reason === "policy")
+        return "Artifact integrity continuation is disabled by policy. Configure REA_ARTIFACT_INTEGRITY_CONTINUE_ENABLED=true and retry only if continuing after mismatches is approved.";
     if (reason === "unavailable")
-        return "Artifact format is not available on this system. Choose another artifact or supported environment.";
+        return "Artifact processing is unavailable for the current target or policy. Check artifact support and required approvals.";
     if (reason === "format" || reason === "integrity")
         return "Artifact is invalid or has changed. Get a fresh copy and try again.";
     return "Artifact could not be read or written. Check file access and try again.";

package/dist/domain/analysisErrorProjection.js

@@ -21,6 +21,8 @@ export const projectAnalysisError = (error) => {
     };
 };
 const errorCode = (error) => {
+    if (error.cleanupIncomplete)
+        return "cleanup_incomplete";
     if (error instanceof ReplayPlanStaleError)
         return "plan_stale";
     if (error instanceof PermissionRequiredError)
@@ -150,6 +152,7 @@ const requestErrorDetails = (error) => {
             issues: error.issues.map((issue) => ({
                 path: [...issue.path],
                 reason: issue.reason,
+                ...(issue.message === undefined ? {} : { message: issue.message }),
                 ...(issue.expected === undefined ? {} : { expected: issue.expected }),
                 ...(issue.minimum === undefined ? {} : { minimum: issue.minimum }),
                 ...(issue.maximum === undefined ? {} : { maximum: issue.maximum }),
@@ -221,6 +224,12 @@ const providerErrorDetails = (error) => {
         return {
             provider_id: error.providerId,
             operation: error.operation,
+            ...(error.cleanupIncomplete
+                ? {
+                    cleanup: "incomplete",
+                    resources: [...error.cleanupResources],
+                }
+                : {}),
             ...(error.diagnostics === undefined
                 ? {}
                 : { diagnostics: error.diagnostics }),