rea-agents 0.2.1

package/dist/domain/hopperValues.js

@@ -0,0 +1,253 @@
+import { z } from "zod";
+import { AnalysisProtocolError, 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() }));
+const addressedNameMapSchema = z.record(z.string(), z.string());
+const segmentSchema = z.object({
+    name: z.string().default(""),
+    start: z.string().default(""),
+    end: z.string().default(""),
+});
+const addressedPageSchema = z.object({
+    items: z.array(z.object({ address: z.string(), value: z.string() })),
+    next_offset: z.number().int().min(0).nullable(),
+    has_more: z.boolean(),
+});
+const unavailableSchema = z
+    .object({ available: z.literal(false), reason: z.string() })
+    .strict();
+const procedureIdentitySchema = z
+    .object({ address: z.string(), name: z.string() })
+    .strict();
+const boundedSchema = (item) => z
+    .object({
+    items: z.array(item),
+    total: z.number().int().min(0).nullable(),
+    returned: z.number().int().min(0),
+    truncated: z.boolean(),
+    next_offset: z.number().int().min(0).nullable(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.returned !== value.items.length) {
+        context.addIssue({
+            code: "custom",
+            message: "returned must equal the number of items",
+            path: ["returned"],
+        });
+    }
+    if (value.total !== null && value.total < value.returned) {
+        context.addIssue({
+            code: "custom",
+            message: "total cannot be smaller than returned",
+            path: ["total"],
+        });
+    }
+    if (value.next_offset !== null && !value.truncated) {
+        context.addIssue({
+            code: "custom",
+            message: "a continuation requires truncated output",
+            path: ["next_offset"],
+        });
+    }
+});
+const referenceEdgeSchema = z
+    .object({
+    source_address: z.string(),
+    target_address: z.string(),
+    source_procedure: procedureIdentitySchema.nullable(),
+    target_procedure: procedureIdentitySchema.nullable(),
+    kind: unavailableSchema,
+})
+    .strict();
+const functionDossierSchema = z
+    .object({
+    procedure: z
+        .object({
+        address: z.string(),
+        name: z.string(),
+        signature: z.string().nullable(),
+        locals: z.array(z.json()),
+    })
+        .strict(),
+    pseudocode: z
+        .object({
+        text: z.string(),
+        total_chars: z.number().int().min(0),
+        returned_chars: z.number().int().min(0),
+        truncated: z.boolean(),
+        next_offset: z.number().int().min(0).nullable(),
+    })
+        .strict()
+        .superRefine((value, context) => {
+        if (value.returned_chars !== value.text.length) {
+            context.addIssue({
+                code: "custom",
+                message: "returned_chars must equal the text length",
+                path: ["returned_chars"],
+            });
+        }
+        if (value.total_chars < value.returned_chars) {
+            context.addIssue({
+                code: "custom",
+                message: "total_chars cannot be smaller than returned_chars",
+                path: ["total_chars"],
+            });
+        }
+        if (value.next_offset !== null && !value.truncated) {
+            context.addIssue({
+                code: "custom",
+                message: "a continuation requires truncated pseudocode",
+                path: ["next_offset"],
+            });
+        }
+    }),
+    assembly: boundedSchema(z.string()),
+    comments: boundedSchema(z
+        .object({
+        address: z.string(),
+        kind: z.enum(["comment", "inline"]),
+        text: z.string(),
+    })
+        .strict()),
+    callers: boundedSchema(procedureIdentitySchema),
+    callees: boundedSchema(procedureIdentitySchema),
+    incoming_references: boundedSchema(referenceEdgeSchema),
+    outgoing_references: boundedSchema(referenceEdgeSchema),
+    referenced_strings: boundedSchema(z
+        .object({
+        address: z.string(),
+        value: z.string(),
+        source_address: z.string(),
+    })
+        .strict()),
+    referenced_names: boundedSchema(z
+        .object({
+        address: z.string(),
+        value: z.string(),
+        source_address: z.string(),
+    })
+        .strict()),
+    basic_blocks: boundedSchema(z
+        .object({
+        start: z.string(),
+        end: z.string(),
+        successors: z.array(z.string()),
+    })
+        .strict()),
+    instruction_scan: z
+        .object({ scanned: z.number().int().min(0), truncated: z.boolean() })
+        .strict(),
+})
+    .strict();
+/** Strictly parse a complete Hopper function dossier at the provider boundary. */
+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,
+        }));
+};
+/** Parse page entries and continuation metadata returned by list operations. */
+export const parseAddressedPage = (value) => {
+    const parsed = addressedPageSchema.safeParse(value);
+    return parsed.success
+        ? ok({
+            items: parsed.data.items.map(({ address, value: name }) => ({
+                address,
+                name,
+            })),
+            nextOffset: parsed.data.next_offset,
+            hasMore: parsed.data.has_more,
+        })
+        : invalid("addressed page", parsed.error);
+};
+/** Parse Hopper's direct or wrapped procedure map into stable entries. */
+export const parseProcedures = (value) => {
+    const page = parseAddressedPage(value);
+    if (page.ok)
+        return ok(page.value.items);
+    const parsed = procedureMapSchema.safeParse(unwrapProperty(value, "procedures"));
+    return parsed.success
+        ? ok(Object.entries(parsed.data).map(([address, name]) => ({
+            address,
+            name,
+        })))
+        : page;
+};
+/** Parse Hopper's direct or wrapped list of address/name records. */
+export const parseNames = (value) => {
+    const unwrapped = unwrapProperty(value, "names");
+    const page = z
+        .object({
+        items: z.array(z.object({ address: z.string(), value: z.string() })),
+    })
+        .safeParse(unwrapped);
+    if (page.success)
+        return ok(page.data.items.map(({ address, value: name }) => ({ address, name })));
+    const records = addressedNamesSchema.safeParse(unwrapped);
+    if (records.success)
+        return ok(records.data);
+    const map = addressedNameMapSchema.safeParse(unwrapped);
+    return map.success
+        ? ok(Object.entries(map.data).map(([address, name]) => ({ address, name })))
+        : invalid("name list", map.error);
+};
+/** Parse callee/caller strings from direct or wrapped Hopper results. */
+export const parseRelatedAddresses = (value, relation) => {
+    const parsed = z.array(z.string()).safeParse(unwrapProperty(value, relation));
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid(`${relation} list`, parsed.error);
+};
+/** Parse direct or wrapped Hopper segment records. */
+export const parseSegments = (value) => {
+    const parsed = z
+        .array(segmentSchema)
+        .safeParse(unwrapProperty(value, "segments"));
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid("segment list", parsed.error);
+};
+/** Parse direct or wrapped Hopper document names. */
+export const parseDocuments = (value) => {
+    const parsed = z
+        .array(z.string())
+        .safeParse(unwrapProperty(value, "documents"));
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid("document list", parsed.error);
+};
+/** Parse a direct or wrapped list when only its cardinality is required. */
+export const parseListCount = (value, property) => {
+    const unwrapped = unwrapProperty(value, property);
+    const pageTotal = z
+        .object({ total: z.number().int().min(0) })
+        .safeParse(unwrapped);
+    if (pageTotal.success)
+        return ok(pageTotal.data.total);
+    const page = z.object({ items: z.array(z.unknown()) }).safeParse(unwrapped);
+    if (page.success)
+        return ok(page.data.items.length);
+    const list = z.array(z.unknown()).safeParse(unwrapped);
+    if (list.success)
+        return ok(list.data.length);
+    const map = z.record(z.string(), z.unknown()).safeParse(unwrapped);
+    return map.success
+        ? ok(Object.keys(map.data).length)
+        : invalid(`${property} list`, map.error);
+};
+const unwrapProperty = (value, property) => {
+    if (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        property in value) {
+        return value[property] ?? null;
+    }
+    return value;
+};
+const invalid = (expected, cause) => err(new HopperProtocolError(`Hopper returned an invalid ${expected}`, {
+    cause,
+}));

package/dist/domain/jsonValue.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+/** JSON-safe value shared by domain, application, and adapter boundaries. */
+export const jsonValueSchema = z.json();

package/dist/domain/processCapture.js

@@ -0,0 +1,252 @@
+import { resolve } from "node:path";
+import { z } from "zod";
+const positiveBudget = z.number().int().positive();
+const timedEventBase = { at_ms: z.number().int().nonnegative() };
+/** Exact boundary schema for bounded dynamic process scenarios. */
+export const processScenarioSchema = z
+    .object({
+    approved: z
+        .literal(true)
+        .describe("Explicit per-call acknowledgement that this operation launches the target"),
+    executable: z.string().startsWith("/"),
+    arguments: z.array(z.string()).max(256).default([]),
+    working_directory: z.string().startsWith("/"),
+    environment: z.record(z.string(), z.string()).default({}),
+    inherit_environment: z.array(z.string()).max(64).default([]),
+    secret_aliases: z.array(z.string()).max(64).default([]),
+    filesystem_roots: z.array(z.string().startsWith("/")).max(16).default([]),
+    events: z
+        .array(z.discriminatedUnion("type", [
+        z.object({
+            ...timedEventBase,
+            type: z.literal("input"),
+            data: z.string(),
+        }),
+        z.object({
+            ...timedEventBase,
+            type: z.literal("resize"),
+            columns: z.number().int().min(1).max(1_000),
+            rows: z.number().int().min(1).max(1_000),
+        }),
+        z.object({
+            ...timedEventBase,
+            type: z.literal("signal"),
+            signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),
+        }),
+    ]))
+        .max(1_000)
+        .default([]),
+    timeout_ms: positiveBudget.max(300_000).default(30_000),
+    idle_timeout_ms: positiveBudget.max(300_000).default(30_000),
+    settle_ms: z.number().int().nonnegative().max(10_000).default(100),
+    limits: z
+        .object({
+        output_bytes: positiveBudget.max(10_000_000).default(1_000_000),
+        frames: positiveBudget.max(100_000).default(10_000),
+        files: positiveBudget.max(100_000).default(10_000),
+        file_bytes: positiveBudget.max(100_000_000).default(10_000_000),
+        processes: positiveBudget.max(10_000).default(1_000),
+    })
+        .default({
+        output_bytes: 1_000_000,
+        frames: 10_000,
+        files: 10_000,
+        file_bytes: 10_000_000,
+        processes: 1_000,
+    }),
+    normalization: z
+        .object({
+        paths: z.boolean().default(true),
+        pids: z.boolean().default(true),
+        ports: z.boolean().default(true),
+        time_bucket_ms: positiveBudget.max(60_000).default(10),
+        patterns: z
+            .array(z.object({
+            pattern: z.string().max(500),
+            replacement: z.string().max(100),
+        }))
+            .max(32)
+            .default([]),
+    })
+        .default({
+        paths: true,
+        pids: true,
+        ports: true,
+        time_bucket_ms: 10,
+        patterns: [],
+    }),
+    replay: z
+        .object({
+        http: z
+            .array(z.object({
+            method: z.string().max(16),
+            path: z.string().startsWith("/"),
+            status: z.number().int().min(100).max(599),
+            body: z.string().max(1_000_000),
+        }))
+            .max(100)
+            .default([]),
+        websocket_messages: z
+            .array(z.string().max(1_000_000))
+            .max(100)
+            .default([]),
+    })
+        .default({ http: [], websocket_messages: [] }),
+})
+    .strict()
+    .superRefine((scenario, context) => {
+    for (let index = 1; index < scenario.events.length; index += 1) {
+        if (scenario.events[index].at_ms < scenario.events[index - 1].at_ms) {
+            context.addIssue({
+                code: "custom",
+                message: "events must be ordered by at_ms",
+                path: ["events", index],
+            });
+        }
+    }
+    const secrets = new Set(scenario.secret_aliases);
+    for (const alias of secrets) {
+        if (!(alias in scenario.environment)) {
+            context.addIssue({
+                code: "custom",
+                message: "secret alias has no environment value",
+                path: ["secret_aliases"],
+            });
+        }
+    }
+});
+/** Parse untrusted process scenario input and apply safe default budgets. */
+export const parseProcessScenario = (input) => processScenarioSchema.parse(input);
+const isWithin = (candidate, root) => resolve(candidate) === resolve(root) ||
+    resolve(candidate).startsWith(`${resolve(root)}${resolve(root).endsWith("/") ? "" : "/"}`);
+/** Evaluate scenario authority before any process or filesystem side effect occurs. */
+export const authorizeProcessScenario = (scenario, policy) => {
+    if (!policy.enabled)
+        return { allowed: false, reason: "process capture is disabled" };
+    if (!policy.executableRoots.some((root) => isWithin(scenario.executable, root))) {
+        return { allowed: false, reason: "executable is outside approved roots" };
+    }
+    if (!policy.workingRoots.some((root) => isWithin(scenario.working_directory, root))) {
+        return {
+            allowed: false,
+            reason: "working directory is outside approved roots",
+        };
+    }
+    const requestedNames = [
+        ...Object.keys(scenario.environment),
+        ...scenario.inherit_environment,
+    ];
+    if (requestedNames.some((name) => !policy.allowedEnvironment.includes(name))) {
+        return {
+            allowed: false,
+            reason: "scenario requests an environment variable not allowed by policy",
+        };
+    }
+    if (scenario.filesystem_roots.some((path) => !policy.workingRoots.some((root) => isWithin(path, root)))) {
+        return {
+            allowed: false,
+            reason: "filesystem root is outside approved roots",
+        };
+    }
+    return { allowed: true };
+};
+/** Exact serialized shape of a bounded process capture. */
+export const processCaptureSchema = z.object({
+    schema_version: z.literal(1),
+    frames: z.array(z.object({
+        sequence: z.number().int().nonnegative(),
+        at_ms: z.number().int().nonnegative(),
+        data: z.string(),
+    })),
+    exit: z.object({
+        code: z.number().int().nullable(),
+        signal: z.number().int().nullable(),
+    }),
+    process_samples: z.array(z.object({
+        at_ms: z.number().int().nonnegative(),
+        pid: z.number().int().positive(),
+        parent_pid: z.number().int().nonnegative(),
+        command: z.string(),
+    })),
+    protocol_events: z.array(z.object({
+        sequence: z.number().int().nonnegative(),
+        protocol: z.enum(["http", "websocket"]),
+        direction: z.enum(["request", "response", "received", "sent"]),
+        method: z.string().nullable(),
+        path: z.string().nullable(),
+        data: z.string(),
+    })),
+    files_before: z.array(z.object({
+        path: z.string(),
+        type: z.enum(["file", "directory", "symlink", "other"]),
+        mode: z.number().int().nonnegative(),
+        size: z.number().int().nonnegative(),
+        sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .nullable(),
+        symlink_target: z.string().nullable(),
+    })),
+    files_after: z.array(z.object({
+        path: z.string(),
+        type: z.enum(["file", "directory", "symlink", "other"]),
+        mode: z.number().int().nonnegative(),
+        size: z.number().int().nonnegative(),
+        sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .nullable(),
+        symlink_target: z.string().nullable(),
+    })),
+    truncated: z.boolean(),
+    limitations: z.array(z.string()),
+});
+const stableFiles = (files) => JSON.stringify([...files].sort((left, right) => left.path.localeCompare(right.path)));
+/** Compare bounded captures without claiming equality for incomplete observations. */
+export const compareProcessCaptures = (left, right) => {
+    if (left.truncated || right.truncated) {
+        return {
+            status: "truncated",
+            terminal: "truncated",
+            exit: "truncated",
+            filesystem: "truncated",
+            protocol: "truncated",
+            process: "truncated",
+            limitations: ["At least one capture is truncated."],
+        };
+    }
+    const terminal = left.frames.map(({ data }) => data).join("") ===
+        right.frames.map(({ data }) => data).join("")
+        ? "unchanged"
+        : "changed";
+    const exit = JSON.stringify(left.exit) === JSON.stringify(right.exit)
+        ? "unchanged"
+        : "changed";
+    const filesystem = stableFiles(left.files_after) === stableFiles(right.files_after)
+        ? "unchanged"
+        : "changed";
+    const protocol = JSON.stringify(left.protocol_events) ===
+        JSON.stringify(right.protocol_events)
+        ? "unchanged"
+        : "changed";
+    const process = JSON.stringify(left.process_samples.map(({ command }) => command)) ===
+        JSON.stringify(right.process_samples.map(({ command }) => command))
+        ? "unchanged"
+        : "changed";
+    const status = terminal === "unchanged" &&
+        exit === "unchanged" &&
+        filesystem === "unchanged" &&
+        protocol === "unchanged" &&
+        process === "unchanged"
+        ? "unchanged"
+        : "changed";
+    return {
+        status,
+        terminal,
+        exit,
+        filesystem,
+        protocol,
+        process,
+        limitations: [...left.limitations, ...right.limitations],
+    };
+};

package/dist/domain/result.js

@@ -0,0 +1,4 @@
+/** Construct a successful result. */
+export const ok = (value) => ({ ok: true, value });
+/** Construct a failed result. */
+export const err = (error) => ({ ok: false, error });

package/dist/domain/symbolAnalysis.js

@@ -0,0 +1,68 @@
+const MAX_SCANNED_SYMBOLS = 5_000;
+const MAX_RETURNED_SYMBOLS = 100;
+/** Select Swift class symbols using the legacy `_TtC` convention. */
+export const discoverSwiftClasses = (procedures, pattern) => {
+    const classes = procedures
+        .slice(0, MAX_SCANNED_SYMBOLS)
+        .filter(({ name }) => name.includes("_TtC"))
+        .filter(({ name }) => pattern.length === 0 || name.includes(pattern));
+    return {
+        count: classes.length,
+        classes: classes.slice(0, MAX_RETURNED_SYMBOLS).map(toJsonEntry),
+    };
+};
+/** Select and deduplicate Objective-C class labels. */
+export const discoverObjcClasses = (names, pattern) => {
+    const classes = uniqueByName(names
+        .filter(({ name }) => ["OBJC_CLASS", "OBJC_$_CLASS"].some((marker) => name.includes(marker)) || name.startsWith("_OBJC_"))
+        .filter(({ name }) => pattern.length === 0 || name.includes(pattern)));
+    return {
+        count: classes.length,
+        classes: classes.slice(0, MAX_RETURNED_SYMBOLS).map(toJsonEntry),
+    };
+};
+/** Select and deduplicate Objective-C and Swift protocol labels. */
+export const discoverObjcProtocols = (names) => {
+    const protocols = uniqueByName(names.filter(({ name }) => name.includes("OBJC_PROTOCOL") || name.includes("_TtP")));
+    return {
+        count: protocols.length,
+        protocols: protocols.slice(0, MAX_RETURNED_SYMBOLS).map(toJsonEntry),
+    };
+};
+const SWIFT_CATEGORIES = [
+    ["classes", "_TtC"],
+    ["structs", "_TtV"],
+    ["enums", "_TtO"],
+    ["protocols", "_TtP"],
+    ["extensions", "_TtE"],
+];
+/** Categorize deduplicated Swift mangled symbols. */
+export const categorizeSwiftTypes = (procedures) => {
+    const groups = Object.fromEntries([...SWIFT_CATEGORIES.map(([category]) => category), "other"].map((category) => [category, []]));
+    const seen = new Set();
+    for (const entry of procedures.slice(0, MAX_SCANNED_SYMBOLS)) {
+        if (!entry.name.includes("_Tt") || seen.has(entry.name))
+            continue;
+        seen.add(entry.name);
+        const category = SWIFT_CATEGORIES.find(([, prefix]) => entry.name.startsWith(prefix))?.[0] ?? "other";
+        groups[category]?.push(entry);
+    }
+    const categories = Object.fromEntries(Object.entries(groups).map(([category, items]) => [
+        category,
+        { count: items.length, items: items.slice(0, 50).map(toJsonEntry) },
+    ]));
+    return { total: seen.size, categories };
+};
+const uniqueByName = (entries) => {
+    const seen = new Set();
+    return entries.filter(({ name }) => {
+        if (seen.has(name))
+            return false;
+        seen.add(name);
+        return true;
+    });
+};
+const toJsonEntry = ({ address, name }) => ({
+    address,
+    name,
+});