rea-agents 5.0.0 → 6.1.0

package/dist/domain/native/binaryLayout.js

@@ -0,0 +1,357 @@
+import { z } from "zod";
+const unsignedHex = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/);
+const index = z.number().int().nonnegative();
+const scalar = z.union([z.string(), z.number().int()]);
+const range = z.strictObject({ offset: unsignedHex, bytes: unsignedHex });
+const canonicalBase64 = z
+    .string()
+    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/][AQgw]==|[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=)?$/);
+const name = z.strictObject({
+    display: z.string(),
+    bytes_base64: canonicalBase64.nullable(),
+    location: range.nullable(),
+    unknown_reason: z.string().nullable(),
+});
+/** Explicit local object selection, independent of an active disassembler target. */
+export const inspectBinaryLayoutInputSchema = z.strictObject({
+    path: z
+        .string()
+        .min(1)
+        .describe("Absolute filesystem path to the selected binary"),
+});
+/** File and linked-image evidence; numeric ELF values never pass through unsafe JSON numbers. */
+const binaryLayoutObjectSchema = z.strictObject({
+    artifact: z.strictObject({
+        path: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        bytes: index,
+    }),
+    format: z.literal("elf"),
+    architecture: z.strictObject({
+        machine: z.literal("EM_X86_64"),
+        bits: z.literal(64),
+        byte_order: z.literal("little"),
+    }),
+    image_type: z.enum(["ET_EXEC", "ET_DYN", "ET_REL"]),
+    entry_point: z.strictObject({
+        reported_value: unsignedHex,
+        meaning: z.enum(["linked-virtual-address", "not-applicable", "absent"]),
+        execution_status: z.literal("unknown"),
+    }),
+    runtime_load_base: z.null(),
+    sections: z.array(z.strictObject({
+        index,
+        name,
+        name_offset: unsignedHex,
+        type: scalar,
+        header_location: range,
+        address: unsignedHex,
+        offset: unsignedHex,
+        size: unsignedHex,
+        alignment: unsignedHex,
+        flags: unsignedHex,
+        link: index,
+        info: index,
+        entry_size: unsignedHex,
+        file_backing: z.enum(["file", "none"]),
+    })),
+    segments: z.array(z.strictObject({
+        index,
+        type: scalar,
+        header_location: range,
+        offset: unsignedHex,
+        file_size: unsignedHex,
+        memory_size: unsignedHex,
+        virtual_address: unsignedHex,
+        physical_address: unsignedHex,
+        alignment: unsignedHex,
+        flags: unsignedHex,
+        file_backing: z.enum(["file", "none"]),
+        permissions: z
+            .strictObject({
+            read: z.boolean(),
+            write: z.boolean(),
+            execute: z.boolean(),
+        })
+            .nullable(),
+    })),
+    symbols: z.array(z.strictObject({
+        table_index: index,
+        entry_index: index,
+        name,
+        name_offset: unsignedHex,
+        location: range,
+        value: unsignedHex,
+        value_meaning: z.enum([
+            "undefined",
+            "alignment",
+            "absolute-value",
+            "no-address",
+            "unknown-section-index",
+            "section-offset",
+            "tls-offset",
+            "linked-virtual-address",
+        ]),
+        size: unsignedHex,
+        binding: scalar,
+        type: scalar,
+        visibility: scalar,
+        section_index: scalar,
+    })),
+    relocations: z.array(z.strictObject({
+        section_index: index,
+        entry_index: index,
+        reported_offset: unsignedHex,
+        target: z.discriminatedUnion("kind", [
+            z.strictObject({
+                kind: z.literal("section-offset"),
+                section_index: index,
+                offset: unsignedHex,
+            }),
+            z.strictObject({
+                kind: z.literal("linked-virtual-address"),
+                address: unsignedHex,
+            }),
+            z.strictObject({
+                kind: z.literal("unknown-section"),
+                reported_section_index: index,
+                offset: unsignedHex,
+                unknown_reason: z.enum([
+                    "undefined-section-reference",
+                    "inactive-section-header",
+                ]),
+            }),
+        ]),
+        location: range,
+        type: index,
+        symbol_table_index: index,
+        symbol_index: index,
+        symbol_reference_meaning: z.enum([
+            "zero-symbol-value",
+            "symbol-table-entry",
+        ]),
+        addend: z
+            .string()
+            .regex(/^-?(?:0|[1-9][0-9]{0,18})$/)
+            .nullable(),
+    })),
+    packed_relative_relocations: z.array(z.strictObject({
+        section_index: index,
+        location: range,
+        encoded_bytes_base64: canonicalBase64,
+        entries: z.array(z.strictObject({ decoded_index: index, reported_offset: unsignedHex })),
+        offset_meaning: z.enum(["linked-virtual-address", "unknown"]),
+        evidence_kind: z.literal("derived"),
+        entry_source_locations: z.null(),
+        addends: z.null(),
+    })),
+    relocation_inventory_completeness: z.literal("unknown"),
+    linkage: z.strictObject({
+        needed_libraries: z.array(name),
+        interpreters: z.array(name),
+        got: z.array(z.strictObject({ display_name: z.string(), address: unsignedHex })),
+        plt: z.array(z.strictObject({ display_name: z.string(), address: unsignedHex })),
+        convenience_maps_completeness: z.literal("unknown"),
+        runtime_library_paths: z.null(),
+    }),
+    mitigations: z.strictObject({
+        evidence_kind: z.literal("inferred"),
+        position_independent: z.boolean(),
+        nx_indicator: z.boolean().nullable(),
+        executable_stack_indicator: z.boolean(),
+        stack_canary_indicator: z.boolean(),
+        relro: z.enum(["Partial", "Full"]).nullable(),
+    }),
+    diagnostics: z.strictObject({
+        stdout: z.string(),
+        stderr: z.string(),
+        truncated: z.boolean(),
+    }),
+    limitations: z.array(z.string()),
+});
+/** Decoder payload excludes the artifact identity observed by the owning process boundary. */
+export const binaryLayoutPayloadSchema = binaryLayoutObjectSchema.omit({
+    artifact: true,
+    diagnostics: true,
+});
+/** Check source ranges again at the public boundary, independently of upstream parsing. */
+export const binaryLayoutSchema = binaryLayoutObjectSchema.superRefine((value, context) => {
+    const size = BigInt(value.artifact.bytes);
+    const check = (offset, length, path) => {
+        const start = BigInt(offset);
+        const bytes = BigInt(length);
+        if (start > size || bytes > size - start)
+            context.addIssue({
+                code: "custom",
+                path,
+                message: "Reported file-backed range lies outside the selected artifact.",
+            });
+    };
+    const checkLocation = (where, path) => check(where.offset, where.bytes, path);
+    const checkName = (reported, path) => {
+        if (reported.location !== null)
+            checkLocation(reported.location, [...path, "location"]);
+    };
+    const expectedEntryMeaning = value.image_type === "ET_REL"
+        ? "not-applicable"
+        : value.entry_point.reported_value === "0x0"
+            ? "absent"
+            : "linked-virtual-address";
+    if (value.entry_point.meaning !== expectedEntryMeaning)
+        context.addIssue({
+            code: "custom",
+            path: ["entry_point", "meaning"],
+            message: "Entry meaning must distinguish zero/unused fields from an actual linked address.",
+        });
+    for (const [index, section] of value.sections.entries()) {
+        if ((section.type === "SHT_SYMTAB" || section.type === "SHT_DYNSYM") &&
+            value.sections[section.link]?.type !== "SHT_STRTAB")
+            context.addIssue({
+                code: "custom",
+                path: ["sections", index, "link"],
+                message: "Symbol tables must link to an existing string-table section.",
+            });
+        if (section.index !== index)
+            context.addIssue({
+                code: "custom",
+                path: ["sections", index, "index"],
+                message: "Complete section order must preserve original producer indices.",
+            });
+        checkLocation(section.header_location, [
+            "sections",
+            index,
+            "header_location",
+        ]);
+        checkName(section.name, ["sections", index, "name"]);
+        if (section.file_backing === "file")
+            check(section.offset, section.size, ["sections", index]);
+    }
+    for (const [index, segment] of value.segments.entries()) {
+        if (segment.index !== index)
+            context.addIssue({
+                code: "custom",
+                path: ["segments", index, "index"],
+                message: "Complete segment order must preserve original producer indices.",
+            });
+        checkLocation(segment.header_location, [
+            "segments",
+            index,
+            "header_location",
+        ]);
+        const hasFileBytes = segment.type !== "PT_NULL" && BigInt(segment.file_size) !== 0n;
+        if (segment.file_backing !== (hasFileBytes ? "file" : "none"))
+            context.addIssue({
+                code: "custom",
+                path: ["segments", index, "file_backing"],
+                message: "File backing must follow the reported segment type and file size.",
+            });
+        if ((segment.type === "PT_NULL") !== (segment.permissions === null))
+            context.addIssue({
+                code: "custom",
+                path: ["segments", index, "permissions"],
+                message: "Unused PT_NULL flags have no permission meaning; other segment flags retain their interpretation.",
+            });
+        if (hasFileBytes)
+            check(segment.offset, segment.file_size, ["segments", index]);
+    }
+    for (const [index, symbol] of value.symbols.entries()) {
+        checkLocation(symbol.location, ["symbols", index, "location"]);
+        checkName(symbol.name, ["symbols", index, "name"]);
+    }
+    for (const [index, relocation] of value.relocations.entries())
+        checkLocation(relocation.location, ["relocations", index, "location"]);
+    validateRelocationReferences(value, context);
+    validatePackedRelativeTables(value, context, checkLocation);
+    for (const facet of ["needed_libraries", "interpreters"])
+        for (const [index, reported] of value.linkage[facet].entries())
+            checkName(reported, ["linkage", facet, index]);
+});
+const validateRelocationReferences = (value, context) => {
+    const symbols = new Set(value.symbols.map((symbol) => `${symbol.table_index}:${symbol.entry_index}`));
+    for (const [index, relocation] of value.relocations.entries()) {
+        const owner = value.sections[relocation.section_index];
+        const target = relocation.target;
+        const targetMatches = value.image_type === "ET_REL"
+            ? target.kind === "section-offset"
+                ? target.section_index !== 0 &&
+                    target.section_index === owner?.info &&
+                    value.sections[target.section_index] !== undefined &&
+                    value.sections[target.section_index]?.type !== "SHT_NULL" &&
+                    target.offset === relocation.reported_offset
+                : target.kind === "unknown-section" &&
+                    target.reported_section_index === owner?.info &&
+                    target.offset === relocation.reported_offset &&
+                    (target.reported_section_index === 0
+                        ? target.unknown_reason === "undefined-section-reference"
+                        : value.sections[target.reported_section_index]?.type ===
+                            "SHT_NULL" &&
+                            target.unknown_reason === "inactive-section-header")
+            : target.kind === "linked-virtual-address" &&
+                target.address === relocation.reported_offset;
+        if (!targetMatches)
+            context.addIssue({
+                code: "custom",
+                path: ["relocations", index, "target"],
+                message: "Relocation target must preserve its reported offset and owner reference; SHN_UNDEF and inactive headers remain unknown rather than resolved sections.",
+            });
+        const table = value.sections[relocation.symbol_table_index];
+        const tableExists = relocation.symbol_table_index !== 0 &&
+            (table?.type === "SHT_SYMTAB" || table?.type === "SHT_DYNSYM");
+        const positiveReferenceExists = tableExists &&
+            BigInt(table.entry_size) >= 24n &&
+            BigInt(relocation.symbol_index) <
+                BigInt(table.size) / BigInt(table.entry_size) &&
+            symbols.has(`${relocation.symbol_table_index}:${relocation.symbol_index}`);
+        if ((owner?.type !== "SHT_REL" && owner?.type !== "SHT_RELA") ||
+            owner.link !== relocation.symbol_table_index ||
+            (relocation.symbol_table_index !== 0 && !tableExists) ||
+            (relocation.symbol_index !== 0 && !positiveReferenceExists) ||
+            relocation.symbol_reference_meaning !==
+                (relocation.symbol_index === 0
+                    ? "zero-symbol-value"
+                    : "symbol-table-entry"))
+            context.addIssue({
+                code: "custom",
+                path: ["relocations", index],
+                message: "Relocation must preserve its REL/RELA owner and resolve positive symbol indices through the linked symbol table; index zero uses a zero symbol value.",
+            });
+    }
+};
+const validatePackedRelativeTables = (value, context, checkLocation) => {
+    for (const [tableIndex, table,] of value.packed_relative_relocations.entries()) {
+        checkLocation(table.location, [
+            "packed_relative_relocations",
+            tableIndex,
+            "location",
+        ]);
+        const encodedBytes = (table.encoded_bytes_base64.length * 3) / 4 -
+            (table.encoded_bytes_base64.endsWith("==")
+                ? 2
+                : table.encoded_bytes_base64.endsWith("=")
+                    ? 1
+                    : 0);
+        if (!Number.isInteger(encodedBytes) ||
+            BigInt(encodedBytes) !== BigInt(table.location.bytes))
+            context.addIssue({
+                code: "custom",
+                path: ["packed_relative_relocations", tableIndex],
+                message: "Complete packed table bytes must match its original file range.",
+            });
+        const section = value.sections[table.section_index];
+        if (section?.type !== "SHT_RELR" ||
+            section.offset !== table.location.offset ||
+            section.size !== table.location.bytes)
+            context.addIssue({
+                code: "custom",
+                path: ["packed_relative_relocations", tableIndex, "section_index"],
+                message: "Packed relative evidence must retain its original RELR section identity and range.",
+            });
+        for (const [decoded, entry] of table.entries.entries())
+            if (entry.decoded_index !== decoded)
+                context.addIssue({
+                    code: "custom",
+                    path: ["packed_relative_relocations", tableIndex, "entries", decoded],
+                    message: "Decoded offsets must preserve upstream iterator order.",
+                });
+    }
+};

package/dist/domain/native/fileOffsetPartialObservation.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/native/nativeCallObservation.js

@@ -0,0 +1,186 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+const hexSchema = z.string().regex(/^0x[0-9a-f]+$/u);
+const nativeString = z
+    .string()
+    .regex(/^[^\0]*$/u, "Native launch and breakpoint strings cannot contain NUL");
+/** Objective-C class names and selectors never contain spaces or brackets. */
+const objcName = nativeString
+    .min(1)
+    .regex(/^[^\s[\]]+$/u, "Use the bare name without spaces or brackets");
+const functionBreakpoint = {
+    kind: z.literal("function"),
+    name: nativeString
+        .min(1)
+        .describe("Exact symbol name, such as `open`, a C++ or mangled Swift symbol, or `-[NSString length]`."),
+};
+const objcMethodBreakpoint = {
+    kind: z.literal("objc-method"),
+    selector: objcName.describe("Selector such as `dataTaskWithRequest:completionHandler:`."),
+};
+/** One function or Objective-C method whose entries are observed. */
+export const nativeCallBreakpointSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...functionBreakpoint,
+        module: nativeString
+            .min(1)
+            .optional()
+            .describe("Image file name that defines the symbol, such as `libsystem_kernel.dylib`; omit to match every image."),
+    }),
+    z.strictObject({
+        ...objcMethodBreakpoint,
+        class_name: objcName
+            .optional()
+            .describe("Implementing class; omit to match every class."),
+        method_type: z.enum(["instance", "class", "any"]).default("any"),
+    }),
+]);
+/**
+ * Launch the active Mach-O as an owned process under LLDB and observe calls.
+ * Duration and event bounds keep runtime observation finite.
+ */
+export const nativeCallObservationInputSchema = z.strictObject({
+    breakpoints: z.array(nativeCallBreakpointSchema).min(1),
+    arguments: z.array(nativeString).default([]),
+    environment: z
+        .record(z
+        .string()
+        .min(1)
+        .regex(/^[^=\0]+$/u, "Environment names cannot contain '=' or NUL"), z.string().regex(/^[^\0]*$/u, "Environment values cannot contain NUL"))
+        .default({})
+        .describe("Overrides on top of the environment REA runs with."),
+    working_directory: localPathStringSchema.optional(),
+    duration_ms: z
+        .number()
+        .int()
+        .min(100)
+        .max(600_000)
+        .default(10_000)
+        .describe("Observation window; the process is killed if it is still running."),
+    max_events: z
+        .number()
+        .int()
+        .min(1)
+        .max(100_000)
+        .default(1_000)
+        .describe("Stop observing and kill the process after this many recorded entries."),
+    argument_registers: z
+        .number()
+        .int()
+        .min(0)
+        .max(8)
+        .default(4)
+        .describe("Integer argument registers to record per entry (arm64 has 8, x86_64 has 6)."),
+    backtrace_frames: z
+        .number()
+        .int()
+        .min(0)
+        .max(64)
+        .default(0)
+        .describe("Caller frames to record per entry."),
+});
+/** A code address with the image and symbol LLDB attributes to it. */
+export const nativeCodeLocationSchema = z.strictObject({
+    load_address: hexSchema,
+    file_address: hexSchema.nullable(),
+    module: z.string().nullable(),
+    module_path: z.string().nullable(),
+    symbol: z.string().nullable(),
+});
+/** One observed entry into a requested function or method. */
+export const nativeCallEventSchema = z.strictObject({
+    sequence: z.number().int().nonnegative(),
+    elapsed_ms: z.number().nonnegative(),
+    thread_id: z.number().int().nonnegative(),
+    breakpoint_index: z.number().int().nonnegative(),
+    ...nativeCodeLocationSchema.shape,
+    /** Dynamic class of an instance-method receiver, read without running code. */
+    receiver_class: z.string().nullable(),
+    /** Selector string read from the `_cmd` register of an Objective-C method. */
+    selector: z.string().nullable(),
+    registers: z.array(z.strictObject({ name: z.string(), value: hexSchema })),
+    backtrace: z.array(nativeCodeLocationSchema),
+});
+/** Retained native output with explicit stream completeness and byte counts. */
+export const nativeCapturedOutputSchema = z.strictObject({
+    text: z.string(),
+    /** Bytes observed by the bridge, not a total when complete is false. */
+    bytes: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+    complete: z.boolean(),
+});
+/** Observed calls, the process lifecycle, and breakpoint resolution. */
+export const nativeCallObservationResultSchema = z.strictObject({
+    target: z.strictObject({
+        path: z.string(),
+        sha256: z.string().regex(/^[0-9a-f]{64}$/u),
+        architecture: z.string(),
+        arguments: z.array(z.string()),
+        environment: z.record(z.string(), z.string()),
+        working_directory: z.string().nullable(),
+        launch_identity: z.strictObject({
+            /** A pathname hash does not verify the bytes mapped into the process. */
+            loaded_image_sha256: z.null(),
+            file_device: z.string().nullable(),
+            file_inode: z.string().nullable(),
+            selected_file_sha256: z
+                .string()
+                .regex(/^[0-9a-f]{64}$/u)
+                .nullable(),
+            module_path: z.string().nullable(),
+            module_uuid: z.string().nullable(),
+            stable: z.boolean(),
+        }),
+    }),
+    debugger: z.strictObject({
+        path: z.string(),
+        sha256: z.string().regex(/^[0-9a-f]{64}$/u),
+        version: z.string().nullable(),
+    }),
+    process: z.strictObject({
+        pid: z.number().int().positive(),
+        outcome: z.enum([
+            "exited",
+            "duration-elapsed",
+            "event-limit",
+            "stop-limit",
+            "resource-limit",
+        ]),
+        exit_status: z.number().int().nullable(),
+        exit_description: z.string().nullable(),
+        /** REA confirmed the process is gone when observation ended. */
+        terminated: z.boolean(),
+        elapsed_ms: z.number().nonnegative(),
+        stdout: nativeCapturedOutputSchema,
+        stderr: nativeCapturedOutputSchema,
+        /** Signal and exception stops LLDB reported; the process continued past each. */
+        other_stops: z.array(z.string()),
+    }),
+    breakpoints: z.array(z.strictObject({
+        index: z.number().int().nonnegative(),
+        request: z.discriminatedUnion("kind", [
+            z.strictObject({
+                ...functionBreakpoint,
+                module: z.string().nullable(),
+            }),
+            z.strictObject({
+                ...objcMethodBreakpoint,
+                class_name: z.string().nullable(),
+                method_type: z.enum(["instance", "class", "any"]),
+            }),
+        ]),
+        location_count: z.number().int().nonnegative(),
+        locations: z.array(nativeCodeLocationSchema),
+    })),
+    events: z.array(nativeCallEventSchema),
+    coverage: z.strictObject({
+        status: z.enum(["complete", "partial"]),
+        event_limit_reached: z.boolean(),
+        resource_limit_reached: z.boolean(),
+        /** Aggregate breakpoint-location metadata exhausted its retained-byte budget. */
+        breakpoint_locations_truncated: z.boolean().optional(),
+        /** Requests that matched no code in any image loaded while observing. */
+        unresolved_breakpoints: z.array(z.number().int().nonnegative()),
+    }),
+    limitations: z.array(z.string()),
+});

package/dist/domain/native/nativeCallPartialObservation.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { nativeCallEventSchema, nativeCapturedOutputSchema, } from "./nativeCallObservation.js";
+/** Native call evidence retained when observation fails before a full result. */
+export const nativeCallPartialObservationSchema = z.strictObject({
+    kind: z.literal("native-call-observation"),
+    target: z.strictObject({
+        path: z.string(),
+        sha256: z.string().regex(/^[0-9a-f]{64}$/u),
+        architecture: z.string(),
+        arguments: z.array(z.string()),
+        environment: z.record(z.string(), z.string()),
+        working_directory: z.string().nullable(),
+    }),
+    process: z.strictObject({
+        pid: z.number().int().positive().nullable(),
+        stdout: nativeCapturedOutputSchema.nullable(),
+        stderr: nativeCapturedOutputSchema.nullable(),
+        other_stops: z.array(z.string()),
+    }),
+    debugger: z.strictObject({ version: z.string().nullable() }),
+    events: z.array(nativeCallEventSchema),
+    coverage: z.strictObject({
+        status: z.literal("partial"),
+        reason: z.enum([
+            "cancelled",
+            "timeout",
+            "tracer-failure",
+            "capture-failure",
+            "cleanup-failure",
+        ]),
+    }),
+    limitations: z.array(z.string()),
+});

package/dist/domain/native/objcSwiftMetadata.js

@@ -419,42 +419,3 @@ const parseMetadataAddress = (address) => {
     const value = Number.parseInt(match[1], 16);
     return Number.isSafeInteger(value) ? value : null;
 };
-/** Check if a selector name looks like a getter. */
-export function isGetterSelector(selector) {
-    return /^[a-z][a-zA-Z0-9_]*$/u.test(selector) && !selector.includes(":");
-}
-/** Check if a selector name looks like a setter. */
-export function isSetterSelector(selector) {
-    return selector.startsWith("set") && selector.endsWith(":");
-}
-/** Extract property name from a getter/setter selector. */
-export function propertyNameFromSelector(selector) {
-    if (isSetterSelector(selector)) {
-        const inner = selector.slice(3, -1);
-        return inner.charAt(0).toLowerCase() + inner.slice(1);
-    }
-    if (isGetterSelector(selector)) {
-        return selector;
-    }
-    return null;
-}
-/** Count ObjC methods by type. */
-export function countMethodsByType(methods) {
-    return {
-        instance: methods.filter((m) => m.method_type === "instance").length,
-        class: methods.filter((m) => m.method_type === "class").length,
-        ivar_getter: methods.filter((m) => m.method_type === "ivar_getter").length,
-        ivar_setter: methods.filter((m) => m.method_type === "ivar_setter").length,
-    };
-}
-/** Get all Swift declarations of a specific kind. */
-export function swiftDeclsByKind(decls, kind) {
-    return decls.filter((d) => d.kind === kind);
-}
-/** Check if a database save preserved all expected items. */
-export function isDbSaveComplete(result, expectedNames, expectedComments, expectedBookmarks) {
-    return (result.succeeded &&
-        result.preserved_names >= expectedNames &&
-        result.preserved_comments >= expectedComments &&
-        result.preserved_bookmarks >= expectedBookmarks);
-}