rea-agents 1.2.0 → 1.4.0

package/dist/application/BoundedJsonFiles.js

@@ -0,0 +1,109 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { EvidenceFileError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Read bounded JSON data from a regular file beneath an approved root. */
+export const readBoundedJson = async (path, policy) => {
+    if (policy.roots.length === 0)
+        return err(new EvidenceFileError("read", "disabled"));
+    try {
+        const canonicalPath = await realpath(resolve(path));
+        if (!(await isApproved(canonicalPath, policy.roots)))
+            return err(new EvidenceFileError("read", "outside-root"));
+        const stats = await lstat(canonicalPath);
+        if (!stats.isFile())
+            return err(new EvidenceFileError("read", "not-file"));
+        if (stats.size > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        const encoded = await readFile(canonicalPath);
+        if (encoded.byteLength > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        let decoded;
+        try {
+            decoded = JSON.parse(encoded.toString("utf8"));
+        }
+        catch (cause) {
+            return err(new EvidenceFileError("read", "invalid-json", { cause }));
+        }
+        const limits = validateJsonLimits(decoded, policy);
+        return limits.ok ? ok(decoded) : limits;
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("read", "io", { cause }));
+    }
+};
+/** Atomically write bounded text to a regular file beneath an approved root. */
+export const writeBoundedText = async (encoded, path, overwrite, policy) => {
+    if (policy.roots.length === 0)
+        return err(new EvidenceFileError("write", "disabled"));
+    const bytes = Buffer.byteLength(encoded, "utf8");
+    if (bytes > policy.maxBytes)
+        return err(new EvidenceFileError("write", "too-large"));
+    try {
+        const requestedPath = resolve(path);
+        const canonicalParent = await realpath(dirname(requestedPath));
+        const destination = resolve(canonicalParent, basename(requestedPath));
+        if (!(await isApproved(destination, policy.roots)))
+            return err(new EvidenceFileError("write", "outside-root"));
+        const existing = await lstat(destination).catch((cause) => {
+            if (isFileNotFound(cause))
+                return undefined;
+            throw cause;
+        });
+        if (existing !== undefined) {
+            if (!overwrite)
+                return err(new EvidenceFileError("write", "exists"));
+            if (!existing.isFile() || existing.isSymbolicLink())
+                return err(new EvidenceFileError("write", "not-file"));
+        }
+        await writeFileAtomic(destination, encoded, {
+            encoding: "utf8",
+            mode: 0o600,
+            fsync: true,
+        });
+        return ok({ path: requestedPath, bytes });
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("write", "io", { cause }));
+    }
+};
+const isApproved = async (candidate, roots) => {
+    for (const configuredRoot of roots) {
+        const root = await realpath(resolve(configuredRoot));
+        const relation = relative(root, candidate);
+        if (relation === "" ||
+            (!relation.startsWith("..") && !isAbsolute(relation)))
+            return true;
+    }
+    return false;
+};
+const validateJsonLimits = (root, policy) => {
+    const pending = [
+        { value: root, depth: 0 },
+    ];
+    let nodes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        nodes += 1;
+        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value === "string" &&
+            current.value.length > policy.maxStringLength)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value !== "object" || current.value === null)
+            continue;
+        for (const [key, value] of Object.entries(current.value)) {
+            if (key.length > policy.maxStringLength)
+                return err(new EvidenceFileError("read", "too-large"));
+            pending.push({ value, depth: current.depth + 1 });
+        }
+    }
+    return ok(null);
+};
+const isFileNotFound = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";

package/dist/application/CapabilityInventory.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+const statusSchema = z.object({
+    open: z.boolean(),
+    kind: z.enum(["executable", "database", "archive", "artifact"]).optional(),
+    format: z.string().optional(),
+    capabilities: z.array(z.object({
+        operation: z.string(),
+        available: z.boolean(),
+        reason: z.string().nullable(),
+    })),
+});
+const ENHANCED_REQUIREMENTS = {
+    swift_classes: ["list_procedures"],
+    get_objc_classes: ["list_names"],
+    get_objc_protocols: ["list_names"],
+    batch_decompile: ["procedure_pseudo_code"],
+    get_call_graph: ["procedure_callees", "procedure_callers"],
+    analyze_swift_types: ["list_procedures"],
+    find_xrefs_to_name: ["list_names", "xrefs"],
+    binary_overview: [
+        "list_segments",
+        "list_documents",
+        "list_procedures",
+        "list_strings",
+    ],
+    analyze_function: ["analyze_function"],
+    trace_feature: [
+        "list_strings",
+        "list_procedures",
+        "xrefs",
+        "resolve_containing_procedure",
+    ],
+};
+/** Build stable per-operation availability without hiding familiar tools. */
+export const buildCapabilityInventory = (sessionStatus, policy) => {
+    const status = statusSchema.parse(sessionStatus);
+    const descriptors = new Map(status.capabilities.map((descriptor) => [descriptor.operation, descriptor]));
+    return TOOL_CONTRACTS.map((contract) => {
+        const availability = availabilityFor(contract.name, contract.kind, status.open, status.kind, descriptors, policy);
+        return {
+            name: contract.name,
+            surface: contract.kind,
+            available: availability.reason === "available",
+            reason: availability.reason,
+            remediation: availability.remediation,
+            annotations: {
+                read_only: contract.annotations.readOnlyHint ?? false,
+                destructive: contract.annotations.destructiveHint ?? false,
+                idempotent: contract.annotations.idempotentHint ?? false,
+                open_world: contract.annotations.openWorldHint ?? true,
+            },
+        };
+    }).sort((left, right) => left.name.localeCompare(right.name));
+};
+const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy) => {
+    if (name === "capture_process_scenario" && !policy.processCaptureEnabled)
+        return {
+            reason: "policy_disabled",
+            remediation: "Enable or grant process_capture within the administrator ceiling.",
+        };
+    if (name === "import_evidence_bundle" && policy.evidenceFileRoots === 0)
+        return {
+            reason: "policy_disabled",
+            remediation: "Configure or grant an evidence_read root.",
+        };
+    if (kind === "session")
+        return { reason: "available", remediation: null };
+    if (!targetOpen)
+        return {
+            reason: "target_required",
+            remediation: "Call open_binary with a supported local target.",
+        };
+    if (targetKind !== undefined &&
+        targetKind !== "executable" &&
+        targetKind !== "database" &&
+        (kind === "official-proxy" || kind === "enhanced"))
+        return {
+            reason: "target_unsupported",
+            remediation: "Inventory or extract a native executable, then call open_binary on that executable.",
+        };
+    if (kind === "enhanced")
+        return composedAvailability(name, descriptors);
+    const descriptor = descriptors.get(name);
+    if (descriptor === undefined)
+        return {
+            reason: "provider_missing",
+            remediation: "Install or configure a provider that declares this operation.",
+        };
+    if (!descriptor.available &&
+        descriptor.reason?.toLowerCase().includes("require macos") === true)
+        return {
+            reason: "unsupported_host",
+            remediation: descriptor.reason,
+        };
+    return descriptor.available
+        ? { reason: "available", remediation: null }
+        : {
+            reason: "provider_unavailable",
+            remediation: descriptor.reason ?? "Choose another target or configured provider.",
+        };
+};
+const composedAvailability = (name, descriptors) => {
+    const requirements = ENHANCED_REQUIREMENTS[name];
+    if (requirements === undefined)
+        return {
+            reason: "provider_missing",
+            remediation: "No provider composition is declared for this operation.",
+        };
+    const missing = requirements.find((operation) => !descriptors.has(operation));
+    if (missing !== undefined)
+        return {
+            reason: "provider_missing",
+            remediation: `Configure a provider for required operation ${missing}.`,
+        };
+    const unavailable = requirements
+        .map((operation) => descriptors.get(operation))
+        .find((descriptor) => descriptor?.available === false);
+    if (unavailable !== undefined)
+        return {
+            reason: unavailable.reason?.toLowerCase().includes("require macos") === true
+                ? "unsupported_host"
+                : "provider_unavailable",
+            remediation: unavailable.reason ?? "Choose another target or configured provider.",
+        };
+    return { reason: "available", remediation: null };
+};

package/dist/application/ClientRegistrationStatus.js

@@ -0,0 +1,69 @@
+import { access, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { supportedClients } from "./SupportedClients.js";
+const objectSchema = z.record(z.string(), z.unknown());
+const registrationSchema = z
+    .object({ command: z.string().min(1), args: z.array(z.string()).default([]) })
+    .passthrough();
+/** Inspect supported client registrations without reading their environment. */
+export const readClientRegistrationStatuses = async (home, currentCommandPath = resolve(process.argv[1] ?? "unknown")) => {
+    const statuses = [];
+    for (const client of supportedClients(home)) {
+        if (client.format === "unsupported" || !(await exists(client.markerPath)))
+            continue;
+        try {
+            const content = await readFile(client.configPath, "utf8");
+            const document = objectSchema.parse(client.format === "toml" ? parseToml(content) : JSON.parse(content));
+            const servers = objectSchema.parse(document[client.format === "toml" ? "mcp_servers" : "mcpServers"] ?? {});
+            const raw = servers[PRODUCT_IDENTITY.mcpServerKey];
+            if (raw === undefined) {
+                statuses.push(status(client.name, client.configPath, [], "missing"));
+                continue;
+            }
+            const registration = registrationSchema.parse(raw);
+            const command = [registration.command, ...registration.args];
+            statuses.push(status(client.name, client.configPath, command, registrationAligned(command, currentCommandPath)
+                ? "aligned"
+                : "stale"));
+        }
+        catch (cause) {
+            statuses.push(status(client.name, client.configPath, [], isMissing(cause) ? "missing" : "invalid"));
+        }
+    }
+    return statuses.sort((left, right) => left.client.localeCompare(right.client));
+};
+const registrationAligned = (command, currentCommandPath) => {
+    if (command.length === 4 &&
+        command[0] === "npx" &&
+        command[1] === "-y" &&
+        command[2] === PRODUCT_IDENTITY.packageName &&
+        command[3] === "mcp")
+        return true;
+    return (command.length === 2 &&
+        command[1] === "mcp" &&
+        resolve(command[0] ?? "") === currentCommandPath);
+};
+const status = (client, configPath, command, state) => ({
+    client,
+    config_path: configPath,
+    command,
+    state,
+    remediation: state === "aligned"
+        ? null
+        : "Run rea setup to refresh this registration, then restart the client.",
+});
+const exists = async (path) => {
+    if (path === undefined)
+        return false;
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";

package/dist/application/CrossVersionInventory.js

@@ -0,0 +1,109 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { createEvidence } from "../domain/evidence.js";
+import { AnalysisCancelledError, ArtifactOperationError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { paginateArtifactInventory, } from "./ArtifactInventory.js";
+import { scanAuthorizedArtifactInventory } from "./AuthorizedArtifactInventory.js";
+import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
+export const AUTOMATIC_RUN_LIMITATION = "Automatic cross-version runs compare shipped artifact structure only; they do not execute either version.";
+/** Authorize and scan both inputs once under the same bounded traversal policy. */
+export const scanVersions = async (input, inputRoots, signal, integrityContinueEnabled = false) => {
+    try {
+        if (signal?.aborted === true)
+            return err(new AnalysisCancelledError("find_changed_behavior"));
+        const limits = artifactLimits(input.options);
+        const integrity = {
+            mode: input.integrity_policy,
+            approved: input.integrity_continue_approved,
+            enabled: integrityContinueEnabled,
+            maxMismatches: input.max_integrity_mismatches,
+        };
+        const left = await scanAuthorizedArtifactInventory(input.left_path, inputRoots, limits, signal, integrity);
+        const right = await scanAuthorizedArtifactInventory(input.right_path, inputRoots, limits, signal, integrity);
+        return ok({ left, right });
+    }
+    catch (cause) {
+        if (cause instanceof ArtifactReaderFailure)
+            return err(new ArtifactOperationError("inventory_artifact", cause.reason, cause.details));
+        return err(new ArtifactOperationError("inventory_artifact", "io"));
+    }
+};
+/** Project complete snapshots into bounded, comparable Evidence page sets. */
+export const createInventoryEvidencePages = (input, snapshots) => {
+    const left = inventoryPages(input.left_path, snapshots.left, input);
+    const right = inventoryPages(input.right_path, snapshots.right, input);
+    if (left.length > 100 || right.length > 100)
+        return err(new ArtifactOperationError("inventory_artifact", "limit"));
+    return ok({ left, right });
+};
+/** Reduce a snapshot to the content commitments used by run identity. */
+export const targetFor = (snapshot) => ({
+    root_sha256: snapshot.manifest.root_sha256,
+    graph_sha256: snapshot.manifest.graph_sha256,
+    manifest_id: snapshot.manifest.manifest_id,
+    format: snapshot.manifest.root_format,
+});
+/** Preserve scan and execution limitations in stable order. */
+export const runLimitations = (snapshots) => [
+    ...new Set([
+        ...snapshots.left.limitations.map((item) => `Left: ${item}`),
+        ...snapshots.right.limitations.map((item) => `Right: ${item}`),
+        AUTOMATIC_RUN_LIMITATION,
+    ]),
+].sort((left, right) => left.localeCompare(right));
+const inventoryPages = (path, snapshot, input) => {
+    const options = input.options;
+    const count = Math.max(1, Math.ceil(snapshot.nodes.length / options.page_size), Math.ceil(snapshot.occurrences.length / options.page_size), Math.ceil(snapshot.edges.length / options.page_size));
+    return Array.from({ length: count }, (_, index) => inventoryPage(path, snapshot, input, index * options.page_size));
+};
+const inventoryPage = (path, snapshot, input, offset) => {
+    const options = input.options;
+    const result = paginateArtifactInventory(snapshot, {
+        nodeOffset: offset,
+        nodeLimit: options.page_size,
+        occurrenceOffset: offset,
+        occurrenceLimit: options.page_size,
+        edgeOffset: offset,
+        edgeLimit: options.page_size,
+    });
+    return createEvidence({
+        path,
+        sha256: snapshot.manifest.root_sha256,
+        format: snapshot.manifest.root_format,
+    }, ARTIFACT_GRAPH_PROVIDER, {
+        operation: "inventory_artifact",
+        parameters: {
+            node_offset: offset,
+            node_limit: options.page_size,
+            occurrence_offset: offset,
+            occurrence_limit: options.page_size,
+            edge_offset: offset,
+            edge_limit: options.page_size,
+            max_entries: options.max_entries,
+            max_total_bytes: options.max_total_bytes,
+            max_entry_bytes: options.max_entry_bytes,
+            max_compression_ratio: options.max_compression_ratio,
+            max_depth: options.max_depth,
+            max_path_bytes: options.max_path_bytes,
+            integrity_policy: input.integrity_policy,
+            integrity_continue_approved: input.integrity_continue_approved,
+            max_integrity_mismatches: input.max_integrity_mismatches,
+        },
+        result: jsonValueSchema.parse(result),
+        rawResult: null,
+        limitations: result.limitations,
+        locations: result.occurrences.items.map(({ logical_path: logicalPath }) => ({
+            kind: "artifact-path",
+            path: logicalPath,
+        })),
+    });
+};
+const artifactLimits = (options) => ({
+    maxEntries: options.max_entries,
+    maxTotalBytes: options.max_total_bytes,
+    maxEntryBytes: options.max_entry_bytes,
+    maxCompressionRatio: options.max_compression_ratio,
+    maxDepth: options.max_depth,
+    maxPathBytes: options.max_path_bytes,
+});