rea-agents 0.3.0 → 0.5.0

package/dist/domain/functionDossierEvidence.js

@@ -0,0 +1,171 @@
+import canonicalize from "canonicalize";
+import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
+import { parseEvidence } from "./evidence.js";
+import { functionDossierSchema } from "./hopperValues.js";
+const MAX_PAGES = 100;
+const MAX_ITEMS = 50_000;
+const MAX_PSEUDOCODE_CHARS = 2_000_000;
+const DOSSIER_COLLECTION_FIELDS = [
+    "assembly",
+    "comments",
+    "callers",
+    "callees",
+    "incoming_references",
+    "outgoing_references",
+    "referenced_strings",
+    "referenced_names",
+    "basic_blocks",
+];
+/** Parse and assemble up to 100 mutually consistent analyze_function pages. */
+export const parseFunctionEvidence = (input) => {
+    const values = Array.isArray(input) ? input : [input];
+    if (values.length === 0 || values.length > MAX_PAGES)
+        throw new TypeError("Function comparison requires 1 to 100 Evidence pages");
+    const pages = values.map(parsePage);
+    assertPageGroup(pages);
+    const first = pages[0];
+    if (first === undefined)
+        throw new TypeError("Function comparison requires Evidence pages");
+    const pseudocode = mergePseudocode(pages);
+    const collections = {
+        assembly: mergeCollection(pages, "assembly"),
+        comments: mergeCollection(pages, "comments"),
+        callers: mergeCollection(pages, "callers"),
+        callees: mergeCollection(pages, "callees"),
+        incoming_references: mergeCollection(pages, "incoming_references"),
+        outgoing_references: mergeCollection(pages, "outgoing_references"),
+        referenced_strings: mergeCollection(pages, "referenced_strings"),
+        referenced_names: mergeCollection(pages, "referenced_names"),
+        basic_blocks: mergeCollection(pages, "basic_blocks"),
+    };
+    return {
+        evidence: pages.map(({ evidence }) => evidence),
+        procedure: first.dossier.procedure,
+        provider: first.evidence.provider,
+        subject: first.evidence.subject,
+        pseudocode,
+        collections,
+        instructionScan: first.dossier.instruction_scan,
+        limitations: [
+            ...new Set(pages.flatMap(({ evidence }) => evidence.limitations)),
+        ].sort((left, right) => left.localeCompare(right)),
+    };
+};
+const parsePage = (input) => {
+    const evidence = parseEvidence(input);
+    if (evidence.operation !== "analyze_function")
+        throw new TypeError("Function comparison requires analyze_function Evidence");
+    if (evidence.subject === null)
+        throw new TypeError("Function comparison requires artifact-bound Evidence");
+    return {
+        evidence: { ...evidence, subject: evidence.subject },
+        dossier: functionDossierSchema.parse(evidence.normalized_result),
+        parameters: enhancedInputSchemas.analyze_function.parse(evidence.parameters),
+    };
+};
+const assertPageGroup = (pages) => {
+    const first = pages[0];
+    if (first === undefined)
+        return;
+    const invariant = pageInvariant(first);
+    for (const page of pages)
+        if (canonicalJson(pageInvariant(page)) !== canonicalJson(invariant))
+            throw new TypeError("Function Evidence pages mix subjects, providers, or immutable analysis controls");
+};
+const pageInvariant = (page) => ({
+    subject: {
+        digest: page.evidence.subject?.digest,
+        format: page.evidence.subject?.format,
+        architecture: page.evidence.subject?.architecture,
+    },
+    provider: page.evidence.provider,
+    procedure: page.dossier.procedure,
+    requested_procedure: page.parameters.procedure,
+    include_assembly: page.parameters.include_assembly,
+    max_instructions: page.parameters.max_instructions,
+    instruction_scan: page.dossier.instruction_scan,
+});
+const mergePseudocode = (pages) => {
+    const totals = new Set(pages.map(({ dossier }) => dossier.pseudocode.total_chars));
+    if (totals.size !== 1)
+        throw new TypeError("Function pseudocode pages disagree on total length");
+    const total = pages[0]?.dossier.pseudocode.total_chars ?? 0;
+    if (total > MAX_PSEUDOCODE_CHARS)
+        throw new TypeError("Function pseudocode exceeds comparison limit");
+    const characters = new Map();
+    for (const page of pages) {
+        const offset = page.parameters.pseudocode_offset;
+        for (const [index, character] of [
+            ...page.dossier.pseudocode.text,
+        ].entries())
+            mergeIndexed(characters, offset + index, character, "pseudocode");
+        if (characters.size > MAX_PSEUDOCODE_CHARS)
+            throw new TypeError("Function pseudocode exceeds comparison limit");
+    }
+    const complete = hasCompleteRange(characters, total);
+    return {
+        text: orderedValues(characters).join(""),
+        total,
+        complete,
+        truncated: !complete,
+    };
+};
+const mergeCollection = (pages, field) => {
+    const totals = new Set(pages.map(({ dossier }) => dossier[field].total));
+    if (totals.size !== 1)
+        throw new TypeError(`Function ${field} pages disagree on total count`);
+    const total = pages[0]?.dossier[field].total ?? null;
+    if (total !== null && total > MAX_ITEMS)
+        throw new TypeError(`Function ${field} exceeds comparison item limit`);
+    const items = new Map();
+    for (const page of pages) {
+        const offset = collectionOffset(page, field);
+        for (const [index, item] of page.dossier[field].items.entries())
+            mergeIndexed(items, offset + index, item, field);
+        if (items.size > MAX_ITEMS)
+            throw new TypeError(`Function ${field} exceeds comparison item limit`);
+    }
+    const scanLimited = field !== "assembly" && pageDependsOnScan(field)
+        ? pages.some(({ dossier }) => dossier.instruction_scan.truncated)
+        : false;
+    const unavailable = field === "assembly" &&
+        pages.every(({ parameters }) => !parameters.include_assembly);
+    const complete = !scanLimited &&
+        !unavailable &&
+        total !== null &&
+        hasCompleteRange(items, total);
+    return {
+        items: orderedValues(items),
+        total,
+        complete,
+        truncated: scanLimited || (!unavailable && !complete),
+    };
+};
+const collectionOffset = (page, field) => field === "assembly"
+    ? page.parameters.assembly_offset
+    : page.parameters.collection_offset[field];
+const pageDependsOnScan = (field) => field !== "callers" && field !== "callees";
+const mergeIndexed = (output, index, value, field) => {
+    const previous = output.get(index);
+    if (previous !== undefined &&
+        canonicalJson(previous) !== canonicalJson(value))
+        throw new TypeError(`Function ${field} pages overlap with conflicting data`);
+    output.set(index, value);
+};
+const hasCompleteRange = (values, total) => {
+    if (values.size !== total)
+        return false;
+    for (let index = 0; index < total; index += 1)
+        if (!values.has(index))
+            return false;
+    return true;
+};
+const orderedValues = (values) => [...values.entries()]
+    .sort(([left], [right]) => left - right)
+    .map(([, value]) => value);
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Function Evidence could not be canonicalized");
+    return encoded;
+};

package/dist/domain/hopperValues.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AnalysisProtocolError, HopperProtocolError } from "./errors.js";
+import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
 import { err, ok } from "./result.js";
 const procedureMapSchema = z.record(z.string(), z.string());
 const addressedNamesSchema = z.array(z.object({ address: z.string(), name: z.string() }));
@@ -8,11 +8,34 @@ const segmentSchema = z.object({
     name: z.string().default(""),
     start: z.string().default(""),
     end: z.string().default(""),
+    readable: z.boolean().nullable().default(null),
+    writable: z.boolean().nullable().default(null),
+    executable: z.boolean().nullable().default(null),
 });
-const addressedPageSchema = z.object({
+const addressedPageSchema = z
+    .object({
     items: z.array(z.object({ address: z.string(), value: z.string() })),
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1),
+    total: z.number().int().min(0),
     next_offset: z.number().int().min(0).nullable(),
     has_more: z.boolean(),
+})
+    .superRefine((value, context) => {
+    if (value.has_more && value.next_offset === null) {
+        context.addIssue({
+            code: "custom",
+            message: "a page with more results must provide next_offset",
+            path: ["next_offset"],
+        });
+    }
+    if (!value.has_more && value.next_offset !== null) {
+        context.addIssue({
+            code: "custom",
+            message: "a complete page must not provide next_offset",
+            path: ["next_offset"],
+        });
+    }
 });
 const unavailableSchema = z
     .object({ available: z.literal(false), reason: z.string() })
@@ -20,6 +43,12 @@ const unavailableSchema = z
 const procedureIdentitySchema = z
     .object({ address: z.string(), name: z.string() })
     .strict();
+const localVariableSchema = z
+    .object({
+    description: z.string(),
+    provenance: z.literal("hopper-public-python-api"),
+})
+    .strict();
 const boundedSchema = (item) => z
     .object({
     items: z.array(item),
@@ -61,14 +90,14 @@ const referenceEdgeSchema = z
     kind: unavailableSchema,
 })
     .strict();
-const functionDossierSchema = z
+export const functionDossierSchema = z
     .object({
     procedure: z
         .object({
         address: z.string(),
         name: z.string(),
         signature: z.string().nullable(),
-        locals: z.array(z.json()),
+        locals: z.array(localVariableSchema),
     })
         .strict(),
     pseudocode: z
@@ -81,7 +110,7 @@ const functionDossierSchema = z
     })
         .strict()
         .superRefine((value, context) => {
-        if (value.returned_chars !== value.text.length) {
+        if (value.returned_chars !== [...value.text].length) {
             context.addIssue({
                 code: "custom",
                 message: "returned_chars must equal the text length",
@@ -146,9 +175,7 @@ export const parseFunctionDossier = (value) => {
     const parsed = functionDossierSchema.safeParse(value);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisProtocolError("Invalid analyze_function provider output", {
-            cause: parsed.error,
-        }));
+        : err(new AnalysisOutputError("analyze_function", "provider output did not match the dossier contract", { cause: parsed.error }));
 };
 /** Parse page entries and continuation metadata returned by list operations. */
 export const parseAddressedPage = (value) => {

package/dist/domain/nativeInspection.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+const hexAddress = z.string().regex(/^0x[a-fA-F0-9]+$/u);
+const coverage = (item) => z.object({
+    items: z.array(item),
+    total: z.number().int().min(0).nullable(),
+    exhaustive: z.boolean(),
+    limitations: z.array(z.string()),
+});
+const nativeCommandInvocationSchema = z.object({
+    tool: z.string().min(1),
+    command: z.array(z.string()),
+    tool_version: z.string().nullable(),
+    version_reason: z.string().nullable(),
+    executable_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    exit: z.object({
+        code: z.number().int().nullable(),
+        signal: z.string().nullable(),
+    }),
+    stdout_bytes: z.number().int().min(0),
+    stderr_bytes: z.number().int().min(0),
+    stdout_truncated: z.boolean(),
+    stderr_truncated: z.boolean(),
+});
+const architectureSchema = z.object({
+    name: z.string(),
+    cpu_type: z.string().nullable(),
+    cpu_subtype: z.string().nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    size: z.number().int().min(0).nullable(),
+    alignment: z.number().int().min(0).nullable(),
+});
+const permissionSchema = z.object({
+    read: z.boolean().nullable(),
+    write: z.boolean().nullable(),
+    execute: z.boolean().nullable(),
+    raw: z.string().nullable(),
+});
+const sectionSchema = z.object({
+    segment: z.string(),
+    name: z.string(),
+    address: hexAddress.nullable(),
+    size: z.number().int().min(0).nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    alignment: z.number().int().min(0).nullable(),
+    flags: z.array(z.string()),
+});
+const segmentSchema = z.object({
+    name: z.string(),
+    vm_address: hexAddress.nullable(),
+    vm_size: z.number().int().min(0).nullable(),
+    file_offset: z.number().int().min(0).nullable(),
+    file_size: z.number().int().min(0).nullable(),
+    maximum_permissions: permissionSchema,
+    initial_permissions: permissionSchema,
+    sections: coverage(sectionSchema),
+});
+const symbolSchema = z.object({
+    name: z.string(),
+    address: hexAddress.nullable(),
+    weak: z.boolean().nullable(),
+    reexport: z.boolean().nullable(),
+    source: z.string().nullable(),
+});
+const dependencySchema = z.object({
+    path: z.string(),
+    kind: z.string(),
+    current_version: z.string().nullable(),
+    compatibility_version: z.string().nullable(),
+});
+const loadCommandSchema = z.object({
+    index: z.number().int().min(0),
+    kind: z.string(),
+    file_offset: z.number().int().min(0).nullable(),
+    fields: z.record(z.string(), z.union([z.string(), z.number(), z.null()])),
+});
+const buildMetadataSchema = z.object({
+    platform: z.string().nullable(),
+    minimum_os: z.string().nullable(),
+    sdk: z.string().nullable(),
+    tools: z.array(z.object({ name: z.string(), version: z.string() })),
+});
+export const inspectMachoSchema = z.object({
+    format: z.literal("mach-o"),
+    endian: z.enum(["little", "big"]).nullable(),
+    word_size: z.union([z.literal(32), z.literal(64)]).nullable(),
+    file_type: z.string().nullable(),
+    flags: z.array(z.string()),
+    uuid: z.string().nullable(),
+    entrypoints: coverage(z.object({ file_offset: z.number().int().min(0) })),
+    architectures: coverage(architectureSchema),
+    build_metadata: coverage(buildMetadataSchema),
+    load_commands: coverage(loadCommandSchema),
+    dependencies: coverage(dependencySchema),
+    imports: coverage(symbolSchema),
+    exports: coverage(symbolSchema),
+    segments: coverage(segmentSchema),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const inspectSignatureSchema = z.object({
+    signed: z.boolean(),
+    identifier: z.string().nullable(),
+    team_identifier: z.string().nullable(),
+    format: z.string().nullable(),
+    cdhashes: z.array(z.string()),
+    hash_algorithms: z.array(z.string()),
+    authorities: z.array(z.string()),
+    designated_requirement: z.string().nullable(),
+    entitlements: z.unknown().nullable(),
+    timestamp: z.string().nullable(),
+    hardened_runtime: z.boolean().nullable(),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const inspectPlistSchema = z.object({
+    format: z.enum(["xml", "binary", "json", "unknown"]),
+    value: z.unknown(),
+    bundle: z.object({
+        identifier: z.string().nullable(),
+        executable: z.string().nullable(),
+        name: z.string().nullable(),
+        version: z.string().nullable(),
+        short_version: z.string().nullable(),
+    }),
+    source_path: z.string(),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const listArchitecturesSchema = z.object({
+    architectures: coverage(architectureSchema),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});
+export const demangleSwiftSchema = z.object({
+    symbols: z.array(z.object({
+        input: z.string(),
+        output: z.string(),
+        status: z.enum(["demangled", "unchanged", "invalid"]),
+    })),
+    provenance: z.array(nativeCommandInvocationSchema),
+    limitations: z.array(z.string()),
+});