rea-agents 1.6.0 → 2.0.0

package/dist/contracts/javascriptRuntimeReconciliationExample.js

@@ -0,0 +1,208 @@
+import { createEvidence } from "../domain/evidence.js";
+import { createJavaScriptApplicationGraph, createJavaScriptApplicationNode, } from "../domain/javascriptApplicationGraph.js";
+import { createWebTextArtifact } from "../domain/webContentArtifact.js";
+const applicationSha256 = "1".repeat(64);
+const script = createWebTextArtifact("export const example = true;\n", "text/javascript");
+const inputPath = "/Applications/Example.app/Contents/Resources/app";
+const scriptPath = `${inputPath}/renderer.js`;
+const completeCoverage = {
+    status: "complete",
+    truncated: false,
+    omitted_count: 0,
+    limits: [],
+};
+const graphEvidence = {
+    authority: "artifact-bytes",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: true,
+        artifact_id: `art_${script.sha256}`,
+        sha256: script.sha256,
+    },
+    location: {
+        available: true,
+        value: { kind: "artifact-path", path: "renderer.js" },
+    },
+    extractor: {
+        name: "rea-javascript-application",
+        version: "1",
+        operation: "inventory-relevant-file",
+        executable_sha256: null,
+    },
+    coverage: completeCoverage,
+    limitations: [],
+    evidence_ids: [],
+};
+const asset = createJavaScriptApplicationNode({
+    kind: "javascript-asset",
+    identity: {
+        strategy: "content-digest",
+        stability: "global-exact",
+        sha256: script.sha256,
+    },
+    observations: [
+        {
+            label: "renderer.js",
+            properties: { path: "renderer.js", bytes: script.bytes },
+            evidence: graphEvidence,
+        },
+    ],
+});
+const graph = createJavaScriptApplicationGraph({
+    schema: "JavaScriptApplicationGraph",
+    schema_version: 1,
+    root_node_ids: [asset.node_id],
+    nodes: [asset],
+    edges: [],
+    coverage: completeCoverage,
+    limitations: [],
+});
+const staticEvidence = createEvidence({ path: inputPath, sha256: applicationSha256, format: "directory" }, {
+    id: "rea-javascript-application",
+    name: "REA JavaScript application analyzer",
+    version: "1",
+}, {
+    predicateType: "rea.javascript-application-analysis/v1",
+    operation: "analyze_javascript_application",
+    parameters: { approved: true, source_map_read_approved: false },
+    result: {
+        schema_version: 1,
+        input_path: inputPath,
+        format: "directory",
+        root_artifact_sha256: applicationSha256,
+        inventory_manifest_id: `agm_${"2".repeat(64)}`,
+        inventory_graph_sha256: "3".repeat(64),
+        graph,
+        summary: {
+            browser_windows: 0,
+            explicit_web_preferences: 0,
+            preload_entrypoints: 0,
+            context_bridge_apis: 0,
+            exposed_api_members: 0,
+            ipc: {
+                operations: 0,
+                literal_channels: 0,
+                dynamic_channel_operations: 0,
+                renderer_transmissions: 0,
+                renderer_listeners: 0,
+                main_handlers: 0,
+                paired_renderer_transmissions: 0,
+                ambiguous_renderer_transmissions: 0,
+                unpaired_literal_renderer_transmissions: 0,
+            },
+            sender_validation_observations: 0,
+            utility_processes: 0,
+            resolved_utility_entrypoints: 0,
+            native_addon_bindings: 0,
+            resolved_native_addon_bindings: 0,
+        },
+        statistics: {
+            relevant_files: 1,
+            nested_asar_containers: 0,
+            text_files_selected: 1,
+            text_bytes_read: script.bytes,
+            omitted_text_files: 0,
+            limit_omitted_text_files: 0,
+            policy_filtered_text_files: 0,
+            invalid_utf8_files: 0,
+            parsed_javascript_files: 1,
+            visited_ast_nodes: 1,
+            findings: 0,
+            modules: 0,
+            parse_failures: 0,
+            truncated_scopes: 0,
+        },
+        limitations: [],
+    },
+    confidence: "derived",
+    authority: "shipped-artifact",
+});
+/** Minimal valid static application Evidence for graph workflow examples. */
+export const JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE = staticEvidence;
+const runtimeEvidence = createEvidence(undefined, {
+    id: "rea-cdp-electron",
+    name: "REA Electron file-page CDP observation provider",
+    version: "1",
+}, {
+    predicateType: "rea.electron-page-inspection/v1",
+    operation: "inspect_electron_page",
+    parameters: {
+        cdp_endpoint: "http://127.0.0.1:9223",
+        allowed_file_roots: [inputPath],
+        target_id: "example-target",
+        include_script_sources: true,
+        source_capture_approved: true,
+    },
+    result: {
+        schema_version: 1,
+        browser: {
+            product: "Electron/example",
+            protocol_version: "1.3",
+            revision: "example",
+            user_agent: "Electron example",
+            js_version: "1",
+        },
+        target: {
+            target_id: "example-target",
+            type: "page",
+            title: "Example",
+            file_path: `${inputPath}/index.html`,
+            attached: false,
+        },
+        capture_window: {
+            started_at: "2026-07-15T00:00:00.000Z",
+            ended_at: "2026-07-15T00:00:00.100Z",
+            observation_ms: 100,
+        },
+        completeness: browserCompleteness(),
+        frames: [],
+        dom: { total_nodes: 0, nodes: [] },
+        scripts: {
+            total: 1,
+            items: [
+                {
+                    script_key: `electron_script_${"4".repeat(64)}`,
+                    frame_id: null,
+                    file_path: scriptPath,
+                    cdp_hash: "example",
+                    length: script.bytes,
+                    is_module: true,
+                    language: "JavaScript",
+                    source: { included: true, artifact: script },
+                },
+            ],
+        },
+        resources: [],
+        workers: [],
+        limitations: ["Example passive capture."],
+    },
+    confidence: "observed",
+    authority: "external-service",
+});
+/** Compact valid Evidence pair used by the public reconciliation contract. */
+export const JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE = {
+    static_layers: [{ role: "application", analysis: staticEvidence }],
+    runtime_observations: [runtimeEvidence],
+};
+function browserCompleteness() {
+    return {
+        status: "complete_within_window",
+        conditions: ["complete_within_window"],
+        policy_filtered_sections: [],
+        attach_limited_sections: [],
+        truncated_sections: [],
+        unavailable_sections: [],
+        excluded: [],
+        dropped_events: {
+            scripts: 0,
+            network_requests: 0,
+            console_events: 0,
+            websocket_connections: 0,
+            websocket_frames: 0,
+            webmcp_tools: 0,
+            timeline_events: 0,
+            total: 0,
+        },
+    };
+}

package/dist/contracts/managedToolContracts.js

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { managedOutputSchemas } from "./toolOutputSchemas.js";
+import { toolContractMetadata } from "./toolEffects.js";
+/** Exact caller boundary for execution-free PE/CLI triage and identity. */
+export const managedArtifactInputSchema = z.object({
+    reference_offset: z.number().int().min(0).default(0),
+    reference_limit: z.number().int().min(1).max(500).default(100),
+    resource_offset: z.number().int().min(0).default(0),
+    resource_limit: z.number().int().min(1).max(500).default(100),
+    attribute_offset: z.number().int().min(0).default(0),
+    attribute_limit: z.number().int().min(1).max(500).default(100),
+    max_file_bytes: z
+        .number()
+        .int()
+        .min(4_096)
+        .max(1_073_741_824)
+        .default(268_435_456),
+    max_metadata_bytes: z
+        .number()
+        .int()
+        .min(256)
+        .max(268_435_456)
+        .default(67_108_864),
+    max_table_rows: z.number().int().min(1).max(1_000_000).default(100_000),
+    max_heap_item_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(16_777_216)
+        .default(1_048_576),
+});
+/** Exact caller boundary for execution-free metadata/signature/IL inspection. */
+export const managedMemberInputSchema = z.object({
+    type_offset: z.number().int().min(0).default(0),
+    type_limit: z.number().int().min(1).max(500).default(100),
+    method_offset: z.number().int().min(0).default(0),
+    method_limit: z.number().int().min(1).max(500).default(100),
+    field_offset: z.number().int().min(0).default(0),
+    field_limit: z.number().int().min(1).max(500).default(100),
+    member_ref_offset: z.number().int().min(0).default(0),
+    member_ref_limit: z.number().int().min(1).max(500).default(100),
+    edge_offset: z.number().int().min(0).default(0),
+    edge_limit: z.number().int().min(1).max(1_000).default(250),
+    instruction_anchor_limit: z.number().int().min(0).max(500).default(100),
+    max_file_bytes: z
+        .number()
+        .int()
+        .min(4_096)
+        .max(1_073_741_824)
+        .default(268_435_456),
+    max_metadata_bytes: z
+        .number()
+        .int()
+        .min(256)
+        .max(268_435_456)
+        .default(67_108_864),
+    max_table_rows: z.number().int().min(1).max(1_000_000).default(100_000),
+    max_heap_item_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(16_777_216)
+        .default(1_048_576),
+    max_method_body_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(16_777_216)
+        .default(1_048_576),
+    max_method_instructions: z.number().int().min(1).max(100_000).default(10_000),
+});
+/** Exact caller boundary for execution-free managed/native boundary inspection. */
+export const managedNativeBoundaryInputSchema = z.object({
+    module_ref_offset: z.number().int().min(0).default(0),
+    module_ref_limit: z.number().int().min(1).max(500).default(100),
+    import_offset: z.number().int().min(0).default(0),
+    import_limit: z.number().int().min(1).max(500).default(100),
+    implementation_offset: z.number().int().min(0).default(0),
+    implementation_limit: z.number().int().min(1).max(500).default(100),
+    max_file_bytes: z
+        .number()
+        .int()
+        .min(4_096)
+        .max(1_073_741_824)
+        .default(268_435_456),
+    max_metadata_bytes: z
+        .number()
+        .int()
+        .min(256)
+        .max(268_435_456)
+        .default(67_108_864),
+    max_table_rows: z.number().int().min(1).max(1_000_000).default(100_000),
+    max_heap_item_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(16_777_216)
+        .default(1_048_576),
+});
+const outputSchema = managedOutputSchemas.inspect_managed_artifact;
+if (outputSchema === undefined)
+    throw new Error("Missing managed output schema for inspect_managed_artifact");
+const memberOutputSchema = managedOutputSchemas.inspect_managed_members;
+if (memberOutputSchema === undefined)
+    throw new Error("Missing managed output schema for inspect_managed_members");
+const nativeBoundaryOutputSchema = managedOutputSchemas.inspect_managed_native_boundaries;
+if (nativeBoundaryOutputSchema === undefined)
+    throw new Error("Missing managed output schema for inspect_managed_native_boundaries");
+/** Read-only managed artifact contracts. */
+export const MANAGED_TOOL_CONTRACTS = [
+    {
+        name: "inspect_managed_artifact",
+        ...toolContractMetadata("inspect_managed_artifact"),
+        description: "Classify the active PE/CLI artifact and inventory exact assembly/module identity, target framework evidence, references, resources, and custom attributes without loading or executing target code. Returns bounded pages and explicit partial or malformed coverage.",
+        kind: "managed-provider",
+        inputSchema: managedArtifactInputSchema,
+        outputSchema,
+        examples: [
+            {
+                title: "Example inspect managed artifact request",
+                input: {},
+            },
+        ],
+    },
+    {
+        name: "inspect_managed_members",
+        ...toolContractMetadata("inspect_managed_members"),
+        description: "Inspect bounded PE/CLI metadata members, signatures, method body IL hashes, exception regions, call edges, and field-access anchors without loading or executing target code. Metadata tokens are reported as build-local coordinates bound to the artifact SHA-256 and MVID.",
+        kind: "managed-provider",
+        inputSchema: managedMemberInputSchema,
+        outputSchema: memberOutputSchema,
+        examples: [
+            {
+                title: "Example inspect managed members request",
+                input: { method_limit: 25, edge_limit: 100 },
+            },
+        ],
+    },
+    {
+        name: "inspect_managed_native_boundaries",
+        ...toolContractMetadata("inspect_managed_native_boundaries"),
+        description: "Inspect PE/CLI ModuleRef, ImplMap/PInvoke declarations, CLI native-header indicators, and non-IL method implementation flags without loading or executing target code. Results are managed declarations and degraded native-boundary observations, not verified native exports or addresses.",
+        kind: "managed-provider",
+        inputSchema: managedNativeBoundaryInputSchema,
+        outputSchema: nativeBoundaryOutputSchema,
+        examples: [
+            {
+                title: "Example inspect managed/native boundary request",
+                input: { import_limit: 50, implementation_limit: 50 },
+            },
+        ],
+    },
+];

package/dist/contracts/managedWorkflowExamples.js

@@ -0,0 +1,346 @@
+import { createEvidence } from "../domain/evidence.js";
+const MANAGED_STATIC_EXAMPLE_PROVIDER = {
+    id: "rea-dotnet-static",
+    name: "REA managed static analysis provider",
+    version: "1",
+};
+const NATIVE_EXAMPLE_PROVIDER = {
+    id: "native-macos",
+    name: "REA native macOS provider",
+    version: "1",
+};
+const emptyManagedMembers = (sha256, mvid) => ({
+    schema_version: 1,
+    artifact: {
+        path: `/examples/${sha256.slice(0, 8)}.dll`,
+        sha256,
+        byte_length: 4096,
+        format: "pe",
+    },
+    module: {
+        name: "Example.dll",
+        generation: 0,
+        mvid,
+        enc_id: null,
+        enc_base_id: null,
+        token: "0x00000001",
+        row_offset: 0,
+    },
+    metadata: {
+        status: "complete",
+        version: "v4.0.30319",
+        table_row_counts: {},
+    },
+    identity_scope: {
+        token_identity: "build-local",
+        requires_artifact_sha256: sha256,
+        requires_mvid: mvid,
+    },
+    types: emptyPage(100),
+    fields: emptyPage(100),
+    methods: emptyPage(100),
+    member_refs: emptyPage(100),
+    call_edges: emptyPage(250),
+    field_accesses: emptyPage(250),
+    coverage: { state: "complete", issues: [] },
+    limitations: [],
+});
+const emptyPage = (limit) => ({
+    items: [],
+    offset: 0,
+    limit,
+    total: 0,
+    returned: 0,
+    dropped: 0,
+    complete: true,
+});
+const evidence = (result) => createEvidence(undefined, MANAGED_STATIC_EXAMPLE_PROVIDER, {
+    operation: "inspect_managed_members",
+    parameters: {},
+    result,
+    rawResult: null,
+    limitations: result.limitations,
+});
+const runtimeMembers = () => {
+    const result = emptyManagedMembers("2".repeat(64), "11112222-3333-4444-9555-666677778888");
+    return {
+        ...result,
+        methods: {
+            ...result.methods,
+            items: [
+                {
+                    token: "0x06000001",
+                    row_offset: 128,
+                    declaring_type_token: "0x02000001",
+                    declaring_type: "Example.Program",
+                    name: "Main",
+                    rva: 8192,
+                    impl_flags: 0,
+                    flags: 22,
+                    signature: {
+                        raw_length: 3,
+                        raw_sha256: "3".repeat(64),
+                        kind: "method",
+                        parse_status: "decoded",
+                        calling_convention: "default",
+                        generic_parameter_count: 0,
+                        parameter_count: 0,
+                        return_type: "void",
+                        parameter_types: [],
+                        field_type: null,
+                        issue: null,
+                    },
+                    body: {
+                        status: "present",
+                        header_format: "tiny",
+                        rva: 8192,
+                        file_offset: 512,
+                        max_stack: 8,
+                        init_locals: false,
+                        local_var_sig_token: null,
+                        il_size: 1,
+                        il_sha256: "4".repeat(64),
+                        normalized_il_sha256: "5".repeat(64),
+                        instruction_count: 1,
+                        decoded_instruction_count: 1,
+                        truncated_instructions: 0,
+                        opcode_counts: { ret: 1 },
+                        anchors: [],
+                        exception_regions: [],
+                        issue: null,
+                    },
+                },
+            ],
+            total: 1,
+            returned: 1,
+        },
+    };
+};
+/** Minimal valid managed member comparison request for public contracts. */
+export const MANAGED_MEMBER_COMPARISON_EXAMPLE = {
+    left: evidence(emptyManagedMembers("0".repeat(64), "00112233-4455-6677-8899-aabbccddeeff")),
+    right: evidence(emptyManagedMembers("1".repeat(64), "ffeeddcc-bbaa-4988-9766-554433221100")),
+    limits: {
+        max_method_matches: 100,
+        max_field_matches: 50,
+        max_candidates: 25,
+    },
+};
+const runtimeExampleEvidence = evidence(runtimeMembers());
+/** Minimal valid managed application graph projection request. */
+export const MANAGED_APPLICATION_GRAPH_EXAMPLE = {
+    managed_members: runtimeExampleEvidence,
+    limits: {
+        max_types: 100,
+        max_methods: 100,
+        max_fields: 100,
+        max_pinvoke_imports: 100,
+        max_native_implementations: 100,
+    },
+};
+const boundaryEvidence = () => {
+    const result = {
+        schema_version: 1,
+        artifact: {
+            path: "/examples/ManagedInterop.exe",
+            sha256: "6".repeat(64),
+            byte_length: 8192,
+            format: "pe",
+        },
+        module: {
+            name: "ManagedInterop.exe",
+            generation: 0,
+            mvid: "00112233-4455-4677-8899-aabbccddeeff",
+            enc_id: null,
+            enc_base_id: null,
+            token: "0x00000001",
+            row_offset: 0,
+        },
+        metadata: {
+            status: "complete",
+            version: "v4.0.30319",
+            table_row_counts: {},
+        },
+        identity_scope: {
+            token_identity: "build-local",
+            requires_artifact_sha256: "6".repeat(64),
+            requires_mvid: "00112233-4455-4677-8899-aabbccddeeff",
+        },
+        cli_native: {
+            il_only: true,
+            requires_32bit: false,
+            strong_name_signed: false,
+            native_entry_point: false,
+            ready_to_run_signature: false,
+            managed_native_header_rva: 0,
+            managed_native_header_size: 0,
+        },
+        module_refs: {
+            items: [
+                {
+                    token: "0x1a000001",
+                    row_offset: 256,
+                    name: "nativehelper.dll",
+                },
+            ],
+            offset: 0,
+            limit: 100,
+            total: 1,
+            returned: 1,
+            dropped: 0,
+            complete: true,
+        },
+        pinvoke_imports: {
+            items: [
+                {
+                    token: "0x1c000001",
+                    row_offset: 288,
+                    mapping_flags: 0,
+                    mapping_flags_hex: "0x0000",
+                    member_token: "0x06000001",
+                    member_kind: "method",
+                    member_name: "OpenNative",
+                    import_name: "open_native",
+                    import_scope_token: "0x1a000001",
+                    import_scope_name: "nativehelper.dll",
+                    no_mangle: true,
+                    char_set: "not-specified",
+                    call_convention: "cdecl",
+                    supports_last_error: false,
+                    best_fit: "assembly-default",
+                    throw_on_unmappable_char: "assembly-default",
+                    verification: "managed-declaration-only",
+                },
+            ],
+            offset: 0,
+            limit: 100,
+            total: 1,
+            returned: 1,
+            dropped: 0,
+            complete: true,
+        },
+        native_implementations: emptyPage(100),
+        summary: {
+            module_ref_count: 1,
+            pinvoke_import_count: 1,
+            native_implementation_count: 0,
+            ready_to_run: false,
+            mixed_mode_or_native_header: false,
+        },
+        coverage: { state: "complete", issues: [] },
+        limitations: [],
+    };
+    return createEvidence(undefined, MANAGED_STATIC_EXAMPLE_PROVIDER, {
+        operation: "inspect_managed_native_boundaries",
+        parameters: {},
+        result,
+        rawResult: null,
+        limitations: result.limitations,
+    });
+};
+const nativeExportEvidence = () => {
+    const result = {
+        format: "mach-o",
+        endian: "little",
+        word_size: 64,
+        file_type: "dylib",
+        flags: [],
+        uuid: null,
+        entrypoints: coverage([]),
+        architectures: coverage([]),
+        build_metadata: coverage([]),
+        load_commands: coverage([]),
+        dependencies: coverage([]),
+        imports: coverage([]),
+        exports: coverage([
+            {
+                name: "open_native",
+                address: "0x1000",
+                weak: false,
+                reexport: false,
+                source: "nm",
+            },
+        ]),
+        segments: coverage([]),
+        provenance: [],
+        limitations: [],
+    };
+    return createEvidence({
+        path: "/examples/nativehelper.dll",
+        sha256: "7".repeat(64),
+        format: "mach-o",
+        architecture: "x86_64",
+    }, NATIVE_EXAMPLE_PROVIDER, {
+        operation: "inspect_macho",
+        parameters: {},
+        result,
+        rawResult: null,
+        limitations: result.limitations,
+    });
+};
+const coverage = (items) => ({
+    items: [...items],
+    total: items.length,
+    exhaustive: true,
+    limitations: [],
+});
+/** Minimal valid managed decompiler reconstruction import request. */
+export const MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE = {
+    static_members: runtimeExampleEvidence,
+    decompiler: {
+        name: "ilspycmd",
+        version: "9.1.0.7988",
+        family: "ilspy",
+        executable_sha256: null,
+        options: ["--disable-updatecheck", "--type", "Example.Program"],
+    },
+    methods: [
+        {
+            token: "0x06000001",
+            signature_sha256: "3".repeat(64),
+            normalized_il_sha256: "5".repeat(64),
+            reconstruction: {
+                kind: "decompiled-csharp",
+                language: "csharp",
+                text: "internal static void Main() { }",
+                source_path: "/examples/Example.Program.cs",
+                start_line: 1,
+                end_line: 1,
+            },
+        },
+    ],
+    notes: [
+        "Synthetic example only; decompiler output is imported as inference.",
+    ],
+};
+/** Minimal valid managed/native verification request. */
+export const MANAGED_NATIVE_VERIFICATION_EXAMPLE = {
+    managed_boundaries: boundaryEvidence(),
+    native_observations: [nativeExportEvidence()],
+    limits: {
+        max_native_observations: 20,
+        max_candidates_per_import: 25,
+    },
+};
+/** Minimal valid managed runtime-correlation planning request. */
+export const MANAGED_RUNTIME_CORRELATION_EXAMPLE = {
+    static_members: runtimeExampleEvidence,
+    method: {
+        token: "0x06000001",
+        signature_sha256: "3".repeat(64),
+        normalized_il_sha256: "5".repeat(64),
+    },
+    requested_effect: "attach",
+    host: {
+        os: "linux",
+        clr_family: "dotnet",
+        architecture: "x86_64",
+    },
+    bounds: {
+        timeout_ms: 5_000,
+        max_threads: 32,
+        max_output_bytes: 65_536,
+        allow_network: false,
+        allow_ui: false,
+    },
+};