rea-agents 2.0.0 → 2.2.0

package/dist/contracts/managedWorkflowToolContracts.js

@@ -111,7 +111,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "compare_managed_members",
         ...toolContractMetadata("compare_managed_members"),
-        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only CIL/signature and structural method-shape tiers. Names are reported as observations but are not used as a matching basis; metadata tokens are remapped as build-local coordinates bound to each artifact SHA-256 and MVID.",
+        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only decoded-CIL-v1/signature and structural method-shape tiers. Names are reported as observations but are not used as a matching basis; metadata tokens remain build-local coordinates bound to each artifact SHA-256 and MVID, and the v1 tuple digest does not itself remap them.",
         kind: "application",
         inputSchema: compareManagedMembersReferenceInputSchema,
         outputSchema: comparisonOutputSchema,
@@ -147,7 +147,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "import_managed_reconstruction",
         ...toolContractMetadata("import_managed_reconstruction"),
-        description: "Import decompiler-produced managed reconstruction against authenticated inspect_managed_members Evidence. The workflow locks each method to artifact SHA-256, MVID, metadata token, signature hash, and normalized IL hash, records the decompiler identity and options, and marks C# or pseudocode as analyst inference rather than canonical byte observation.",
+        description: "Import decompiler-produced managed reconstruction against authenticated inspect_managed_members Evidence. The workflow locks each method to artifact SHA-256, MVID, metadata token, signature hash, and the limited member-result-v1 decoded-IL tuple hash, records the decompiler identity and options, and marks C# or pseudocode as analyst inference rather than canonical byte observation.",
         kind: "application",
         inputSchema: managedReconstructionReferenceInputSchema,
         outputSchema: reconstructionOutputSchema,
@@ -166,7 +166,7 @@ export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {
         name: "plan_managed_runtime_correlation",
         ...toolContractMetadata("plan_managed_runtime_correlation"),
-        description: "Prepare a separately authorized managed runtime-correlation admission plan from authenticated inspect_managed_members Evidence. The operation is default-disabled, requires the managed_runtime permission ceiling and grant, locks the exact artifact SHA-256, MVID, method signature, and normalized IL shape, distinguishes attach/load/debugger/reflection/instrumentation effects, and records that no target code was executed.",
+        description: "Prepare a separately authorized managed runtime-correlation admission plan from authenticated inspect_managed_members Evidence. The operation is default-disabled, requires the managed_runtime permission ceiling and grant, locks the exact artifact SHA-256, MVID, method signature, and limited member-result-v1 decoded-IL tuple hash, distinguishes attach/load/debugger/reflection/instrumentation effects, and records that no target code was executed.",
         kind: "application",
         inputSchema: managedRuntimeCorrelationReferenceInputSchema,
         outputSchema: runtimeOutputSchema,

package/dist/contracts/providerSelection.js

@@ -23,6 +23,8 @@ export const PROVIDER_REJECTION_CODES = [
     "target_kind_unsupported",
     "target_format_unsupported",
     "architecture_unsupported",
+    "target_role_unsupported",
+    "managed_target_unsupported",
     "open_options_invalid",
     "version_unresolved",
 ];

package/dist/contracts/sessionStatusContract.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { TOOL_KINDS } from "./toolContractTypes.js";
+/** Caller observations and projection controls for binary_session. */
+export const binarySessionInputSchema = z.object({
+    detail: z
+        .enum(["summary", "capabilities", "full"])
+        .default("summary")
+        .describe("summary returns routing state; capabilities returns one filtered tool-availability page; full returns complete diagnostics only when required"),
+    capability_family: z
+        .enum(TOOL_KINDS)
+        .optional()
+        .describe("Optional tool family for detail=capabilities"),
+    cursor: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe("Zero-based capability cursor for detail=capabilities"),
+    limit: z.number().int().min(1).max(100).default(25),
+    expected_package_version: z.string().min(1).optional(),
+    expected_catalog_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    expected_server_path: z.string().min(1).optional(),
+});

package/dist/contracts/toolContractTypes.js

@@ -1 +1,12 @@
-export {};
+/** Canonical adapter families responsible for public MCP tools. */
+export const TOOL_KINDS = [
+    "official-proxy",
+    "enhanced",
+    "native-provider",
+    "artifact-provider",
+    "managed-provider",
+    "browser-provider",
+    "electron-provider",
+    "application",
+    "session",
+];

package/dist/contracts/toolContracts.js

@@ -21,6 +21,8 @@ import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
 import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
 import { closeBinaryInputSchema, openBinaryInputSchema, } from "./sessionLifecycleInputs.js";
 import { toolContractMetadata } from "./toolEffects.js";
+import { binarySessionInputSchema } from "./sessionStatusContract.js";
+export { binarySessionInputSchema } from "./sessionStatusContract.js";
 const document = z.string().optional().describe("The document name");
 const address = z
     .string()
@@ -125,8 +127,8 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     })),
     official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters.", z.object({ procedure, document })),
     official("resolve_containing_procedure", "Resolve an arbitrary address, including an interior instruction or exact external entry, to its provider-analyzed containing procedure. A negative result distinguishes outside segments from not in a procedure and is never guessed from nearby symbols.", z.object({ address, document })),
-    official("search_procedures", "Search analyzed procedure names using literal matching by default or regex opt-in. Ghidra bounds literal work and rejects regex constructs, paths, candidates, or cumulative work outside its finite budgets. Results are deterministic and offset-paginated.", z.object(searchInput)),
-    official("search_strings", "Search analyzed strings using literal matching by default or regex opt-in. Ghidra bounds literal work and rejects regex constructs, paths, candidates, or cumulative work outside its finite budgets. Results are deterministic, offset-paginated, and explicitly truncated.", z.object(searchInput)),
+    official("search_procedures", "Search analyzed procedure names using literal matching by default or regex opt-in. Providers bound search work and reject regex constructs, paths, candidates, or cumulative work outside their finite budgets. Results are deterministic and offset-paginated.", z.object(searchInput)),
+    official("search_strings", "Search analyzed strings using literal matching by default or regex opt-in. Providers bound search work and reject regex constructs, paths, candidates, or cumulative work outside their finite budgets. Results are deterministic, offset-paginated, and explicitly truncated.", z.object(searchInput)),
     official("set_address_name", "Assign an analyst name to one hexadecimal address and report Hopper's boolean result. This mutates analysis metadata; read it back with address_name before relying on it.", z.object({ address, name: z.string(), document })),
     official("set_addresses_names", "Assign analyst names to an address/name map and return per-address success booleans. This mutates analysis metadata; use for bounded batches and verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
     official("set_bookmark", "Create or replace a bookmark at a hexadecimal address. This mutates navigation metadata; verify with list_bookmarks and do not treat bookmarks as binary evidence.", z.object({ address, name: z.string().optional(), document })),
@@ -149,15 +151,6 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata.", enhancedInputSchemas.analyze_function),
     enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature),
 ];
-/** Caller observations used to compare a live server with expected identity. */
-export const binarySessionInputSchema = z.object({
-    expected_package_version: z.string().min(1).optional(),
-    expected_catalog_digest: z
-        .string()
-        .regex(/^[a-f0-9]{64}$/u)
-        .optional(),
-    expected_server_path: z.string().min(1).optional(),
-});
 /** Session-owned Evidence bundle export options. */
 export const exportEvidenceBundleInputSchema = z.strictObject({
     path: z.string().min(1).optional(),
@@ -193,7 +186,7 @@ export const verifyUnknownResolutionInputSchema = z.strictObject({
 export const SESSION_TOOL_CONTRACTS = [
     session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. An optional snapshot v2 is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly.", openBinaryInputSchema),
     session("close_binary", "Optionally write a provider-neutral analysis snapshot atomically, then close the active target and every provider resource started for it. Snapshot files require an operator-approved root and explicit overwrite; a failed save leaves the session open so cached analysis is not lost.", closeBinaryInputSchema),
-    session("binary_session", "Report deterministic deep-provider candidates, host availability, target support, the immutable active binding/profile, capability descriptors, and whether a target is open. Candidate discovery never starts an analysis process; use rejection codes and local diagnostics before choosing provider_id.", binarySessionInputSchema),
+    session("binary_session", "Report compact target, provider, and alignment state without starting analysis. The default summary is the routing check agents should use; detail=capabilities returns one family-filtered availability page, while detail=full is reserved for complete provider diagnostics.", binarySessionInputSchema),
     session("export_evidence_bundle", "Return the session's deterministic Evidence v2 bundle, or atomically write it beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", exportEvidenceBundleInputSchema),
     session("import_evidence_bundle", "Read a bounded local JSON bundle beneath an operator-approved root, validate every Evidence v2 ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", importEvidenceBundleInputSchema),
     session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Produces Process Capture v4; legacy v3 captures cannot be upgraded and must be recaptured with this tool. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures raw and xterm-rendered terminal frames, scripted interactions, lifecycle filesystem checkpoints, process ownership, declarative command shims, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.", processScenarioSchema),

package/dist/contracts/toolEffects.js

@@ -99,6 +99,20 @@ export const TOOL_EFFECTS = {
         writesFilesystem: true,
         launchesProcess: true,
     }),
+    prepare_node_characterization: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+    }),
+    execute_node_characterization: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+    }),
+    commit_reconstruction_coverage: effects({
+        writesFilesystem: true,
+        mutatesSession: true,
+    }),
+    query_reconstruction_coverage: effects({ mutatesSession: true }),
     open_binary: effects({ mutatesSession: true, launchesProcess: true }),
     close_binary: effects({
         mutatesSession: true,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -0,0 +1,274 @@
+import { z } from "zod";
+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 { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
+import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { managedArtifactInspectionSchema, managedMemberInspectionSchema, managedNativeBoundaryInspectionSchema, } from "../domain/managedArtifact.js";
+import { managedMemberComparisonResultSchema } from "../domain/managedMemberComparison.js";
+import { managedNativeVerificationResultSchema } from "../domain/managedNativeVerification.js";
+import { managedReconstructionImportResultSchema } from "../domain/managedReconstruction.js";
+import { managedRuntimeCorrelationResultSchema } from "../domain/managedRuntimeCorrelation.js";
+import { managedApplicationGraphResultSchema } from "../domain/managedApplicationGraph.js";
+import { artifactComparisonResultSchema } from "../domain/artifactComparison.js";
+import { functionComparisonResultSchema } from "../domain/functionComparison.js";
+import { bundleComparisonResultSchema } from "../domain/bundleComparison.js";
+import { changedBehaviorResultSchema } from "../domain/changedBehavior.js";
+import { callPathResultSchema } from "../domain/callPath.js";
+import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
+import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.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";
+/** Exact structured-content schemas shared by direct analysis providers. */
+export const officialOutputSchemas = {
+    address_name: resultOf(nullableText),
+    comment: resultOf(nullableText),
+    current_address: resultOf(z.string()),
+    current_procedure: resultOf(z.string()),
+    current_document: resultOf(z.string()),
+    goto_address: resultOf(z.string()),
+    inline_comment: resultOf(nullableText),
+    list_bookmarks: resultOf(z.array(addressedEntry)),
+    list_documents: resultOf(z.array(z.string())),
+    list_names: resultOf(pageOutput),
+    list_procedures: resultOf(pageOutput),
+    list_segments: segmentOutput,
+    list_strings: resultOf(pageOutput),
+    next_address: resultOf(z.string()),
+    prev_address: resultOf(z.string()),
+    procedure_address: resultOf(z.string()),
+    procedure_assembly: resultOf(z.string()),
+    procedure_callees: resultOf(addressList),
+    procedure_callers: resultOf(addressList),
+    procedure_info: procedureInfoOutput,
+    procedure_references: resultOf(z.object({
+        procedure: procedureIdentity,
+        direction: z.enum(["incoming", "outgoing"]),
+        references: bounded(z.object({
+            source_address: z.string(),
+            target_address: z.string(),
+            source_procedure: procedureIdentity.nullable(),
+            target_procedure: procedureIdentity.nullable(),
+            kind: referenceKindSchema,
+        })),
+        instructions_scanned: z.number().int().min(0),
+        instruction_scan_truncated: z.boolean(),
+    })),
+    procedure_pseudo_code: resultOf(nullableText),
+    resolve_containing_procedure: resultOf(containingProcedureResolution),
+    search_procedures: resultOf(searchPageOutput),
+    search_strings: resultOf(searchPageOutput),
+    set_address_name: resultOf(z.boolean()),
+    set_addresses_names: resultOf(z.record(z.string(), z.boolean())),
+    set_bookmark: resultOf(z.boolean()),
+    set_comment: resultOf(z.boolean()),
+    set_current_document: resultOf(z.string()),
+    set_inline_comment: resultOf(z.boolean()),
+    unset_bookmark: resultOf(z.boolean()),
+    xrefs: resultOf(addressList),
+};
+/** Exact structured-content schemas for composed analysis workflows. */
+export const enhancedOutputSchemas = {
+    swift_classes: symbolDiscoveryOutput("classes"),
+    get_objc_classes: symbolDiscoveryOutput("classes"),
+    get_objc_protocols: symbolDiscoveryOutput("protocols"),
+    batch_decompile: resultOf(z.object({
+        items: z.array(z.discriminatedUnion("status", [
+            z.object({
+                address: z.string(),
+                status: z.literal("ok"),
+                pseudocode: z.string().min(1),
+            }),
+            z.object({
+                address: z.string(),
+                status: z.literal("error"),
+                error: analysisErrorProjectionSchema,
+            }),
+        ])),
+        total: z.number().int().min(0),
+        succeeded: z.number().int().min(0),
+        failed: z.number().int().min(0),
+    })),
+    get_call_graph: resultOf(z.record(z.string(), z.array(graphNode))),
+    analyze_swift_types: resultOf(z.object({
+        total: z.number().int().min(0),
+        categories: z.record(z.string(), z.object({
+            count: z.number().int().min(0),
+            items: z.array(addressedEntry),
+        })),
+    })),
+    find_xrefs_to_name: resultOf(z.discriminatedUnion("status", [
+        z.object({
+            status: z.literal("resolved"),
+            name: z.string(),
+            address: z.string(),
+            xrefs: addressList,
+        }),
+        z.object({
+            status: z.literal("unresolved"),
+            name: z.string(),
+            reason: z.literal("name_not_found"),
+        }),
+    ])),
+    binary_overview: resultOf(z.object({
+        document: z.string(),
+        detail: z.enum(["concise", "detailed"]),
+        segments: z.array(z.object({
+            name: z.string(),
+            start: z.string(),
+            end: z.string(),
+            length: z.number().min(0).optional(),
+        })),
+        segment_count: z.number().int().min(0),
+        procedure_count: z.number().int().min(0),
+        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()),
+    })),
+};
+/** Exact Evidence v2 schemas for provider-neutral native inspection. */
+export const nativeOutputSchemas = {
+    inspect_macho: resultOf(inspectMachoSchema),
+    inspect_signature: resultOf(inspectSignatureSchema),
+    inspect_plist: resultOf(inspectPlistSchema),
+    list_architectures: resultOf(listArchitecturesSchema),
+    demangle_swift: resultOf(demangleSwiftSchema),
+};
+/** Exact Evidence v2 schemas for provider-neutral artifact graph operations. */
+export const artifactOutputSchemas = {
+    inventory_artifact: resultOf(artifactInventoryResultSchema),
+    extract_artifact: resultOf(artifactExtractionResultSchema),
+};
+/** Exact Evidence v2 schema for execution-free managed static analysis. */
+export const managedOutputSchemas = {
+    inspect_managed_artifact: resultOf(managedArtifactInspectionSchema),
+    inspect_managed_members: resultOf(managedMemberInspectionSchema),
+    inspect_managed_native_boundaries: resultOf(managedNativeBoundaryInspectionSchema),
+};
+/** Exact Evidence v2 schema for provider-neutral managed workflows. */
+export const managedWorkflowOutputSchemas = {
+    compare_managed_members: resultOf(managedMemberComparisonResultSchema),
+    verify_managed_native_boundaries: resultOf(managedNativeVerificationResultSchema),
+    import_managed_reconstruction: resultOf(managedReconstructionImportResultSchema),
+    plan_managed_runtime_correlation: resultOf(managedRuntimeCorrelationResultSchema),
+    project_managed_application_graph: resultOf(managedApplicationGraphResultSchema),
+};
+/** Exact structured-content schemas for target lifecycle operations. */
+export const sessionOutputSchemas = {
+    open_binary: lifecycleResultOf(z.object({
+        path: z.string(),
+        format: targetFormatSchema,
+        kind: targetKindSchema,
+        loaderArgs: z.array(z.string()),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+    })),
+    close_binary: lifecycleResultOf(z.union([
+        z.null(),
+        z.object({
+            path: z.string(),
+            bytes: z.number().int().min(0),
+            entries: z.number().int().min(0),
+        }),
+    ])),
+    binary_session: lifecycleResultOf(z.union([
+        z.object({
+            view: z.literal("summary"),
+            open: z.boolean(),
+            provider: providerIdentity,
+            active_provider: providerIdentity.nullable(),
+            target: z
+                .object({
+                path: z.string(),
+                format: targetFormatSchema,
+                kind: targetKindSchema,
+                sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+                architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+            })
+                .nullable(),
+            alignment: z.object({
+                state: z.enum(["aligned", "mcp_server_restart_required", "unknown"]),
+                reasons: z.array(z.string()),
+                remediation: z.string().nullable(),
+            }),
+            recommended_actions: z.array(z.string()),
+        }),
+        z.object({
+            view: z.literal("capabilities"),
+            open: z.boolean(),
+            provider: providerIdentity,
+            active_provider: providerIdentity.nullable(),
+            capability_family: z.string().nullable(),
+            capabilities: z.object({
+                items: z.array(toolAvailability),
+                cursor: z.number().int().min(0),
+                limit: z.number().int().min(1),
+                total: z.number().int().min(0),
+                next_cursor: z.number().int().min(0).nullable(),
+                has_more: z.boolean(),
+            }),
+        }),
+        z.union([
+            sessionProvider.extend({
+                view: z.literal("full"),
+                open: z.literal(false),
+            }),
+            sessionProvider.extend({
+                view: z.literal("full"),
+                open: z.literal(true),
+                path: z.string(),
+                format: targetFormatSchema,
+                kind: targetKindSchema,
+                sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+                architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+            }),
+        ]),
+    ])),
+    export_evidence_bundle: lifecycleResultOf(z.union([
+        evidenceBundleSchema,
+        z.object({
+            path: z.string(),
+            bytes: z.number().int().min(0),
+            records: z.number().int().min(0),
+        }),
+    ])),
+    import_evidence_bundle: lifecycleResultOf(z.object({
+        imported: z.number().int().min(0),
+        total: z.number().int().min(0),
+    })),
+    capture_process_scenario: resultOf(processCaptureSchema),
+    compare_process_captures: resultOf(processCaptureComparisonSchema),
+    compare_artifacts: resultOf(artifactComparisonResultSchema),
+    compare_functions: resultOf(functionComparisonResultSchema),
+    compare_bundles: resultOf(bundleComparisonResultSchema),
+    find_changed_behavior: resultOf(changedBehaviorResultSchema),
+    build_call_path: resultOf(callPathResultSchema),
+    correlate_static_and_runtime: resultOf(staticRuntimeCorrelationResultSchema),
+    verify_reconstruction: resultOf(reconstructionVerificationResultSchema),
+    list_unknowns: lifecycleResultOf(z.array(residualUnknownSchema)),
+    record_unknown: lifecycleResultOf(residualUnknownSchema),
+    update_unknown: lifecycleResultOf(residualUnknownSchema),
+    verify_unknown_resolution: lifecycleResultOf(z.object({
+        valid: z.boolean(),
+        truthVerified: z.boolean(),
+        unknown: residualUnknownSchema,
+    })),
+};