rea-agents 1.7.0 → 2.1.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, raw CIL hashes, limited member-result-v1 decoded-instruction-tuple hashes, separately reported 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; the v1 tuple hash does not resolve them or fully commit control flow.",
+        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,
+    },
+};