rea-agents 1.2.0 → 1.3.0

package/dist/domain/changedBehavior.js

@@ -3,13 +3,24 @@ import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
 import { functionComparisonResultSchema } from "./functionComparison.js";
 import { comparisonStatusSchema, processCaptureComparisonSchema, } from "./processCapture.js";
+import { crossVersionInvestigationInputSchema, investigationRunSummarySchema, } from "./investigationWorkspace.js";
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 /** Strict bounded input for aggregating existing comparison Evidence. */
-export const changedBehaviorInputSchema = z.object({
-    comparisons: z.array(evidenceSchema).min(1).max(100),
+export const changedBehaviorInputSchema = z
+    .object({
+    comparisons: z.array(evidenceSchema).max(100).default([]),
+    investigation_run: crossVersionInvestigationInputSchema.optional(),
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(100).default(100),
     unknown_registry_approved: z.literal(true).optional(),
+})
+    .superRefine((input, context) => {
+    if (input.comparisons.length > 0 ===
+        (input.investigation_run !== undefined))
+        context.addIssue({
+            code: "custom",
+            message: "Supply either existing comparisons or one investigation_run, but not both",
+        });
 });
 const findingSchema = z.object({
     scope: z.enum(["runtime", "protocol", "resource", "static_candidate"]),
@@ -48,6 +59,7 @@ export const changedBehaviorResultSchema = z.object({
     }),
     evidence_links: z.array(evidenceIdSchema).min(3).max(20_100),
     limitations: z.array(z.string()),
+    investigation_run: investigationRunSummarySchema.optional(),
 });
 const EXPECTED_PROVIDERS = {
     compare_process_captures: {
@@ -113,6 +125,7 @@ export const findChangedBehavior = (comparisonsInput, offset, limit) => {
             ...(runtimeStatuses.length === 0
                 ? ["No process comparison Evidence was supplied."]
                 : []),
+            ...evidence.flatMap(artifactPaginationLimitations),
         ]),
     });
 };
@@ -169,10 +182,8 @@ const parseResult = (evidence) => {
         return;
     }
     const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
-    if (result.changes.offset !== 0 ||
-        result.changes.next_offset !== null ||
-        result.changes.items.length !== result.changes.total)
-        throw new TypeError("Changed-behavior analysis requires complete artifact comparison pagination");
+    if (result.changes.offset !== 0)
+        throw new TypeError("Changed-behavior analysis requires artifact comparison pagination from offset zero");
     assertNestedLinks(evidence, result.changes.items.flatMap(({ evidence_links: links }) => links));
 };
 const assertNestedLinks = (evidence, nestedLinks) => {
@@ -242,7 +253,9 @@ const artifactFindings = (evidence) => {
         limitations: result.limitations,
         links: change.evidence_links,
     }));
-    return (result.status === "unknown" || result.status === "truncated") &&
+    return (result.status === "unknown" ||
+        result.status === "truncated" ||
+        result.changes.next_offset !== null) &&
         !changes.some(({ classification }) => classification === "unresolved_branch")
         ? [
             ...changes,
@@ -257,6 +270,16 @@ const artifactFindings = (evidence) => {
         ]
         : changes;
 };
+const artifactPaginationLimitations = (evidence) => {
+    if (evidence.operation !== "compare_artifacts")
+        return [];
+    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+    return result.changes.next_offset === null
+        ? []
+        : [
+            `Artifact comparison reports ${String(result.changes.items.length)} of ${String(result.changes.total)} changes.`,
+        ];
+};
 const makeFinding = (input) => findingSchema.parse({
     scope: input.scope,
     dimension: input.dimension,

package/dist/domain/errors.js

@@ -1,5 +1,7 @@
+import { hopperStartupFailure, } from "./hopperStartupFailure.js";
+export { hopperStartupFailure } from "./hopperStartupFailure.js";
 /** Stable tags exposed by safe analysis-error projections. */
-export const ANALYSIS_ERROR_TAGS = [
+const ANALYSIS_ERROR_TAGS = [
     "AnalysisProtocolError",
     "AnalysisInputError",
     "AnalysisOutputError",
@@ -13,6 +15,7 @@ export const ANALYSIS_ERROR_TAGS = [
     "EvidenceIntegrityError",
     "EvidenceLimitError",
     "EvidenceFileError",
+    "InvestigationWorkspaceError",
     "UnknownRegistryError",
     "HopperTimeoutError",
     "HopperCancelledError",
@@ -26,6 +29,8 @@ export const ANALYSIS_ERROR_TAGS = [
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
+    userMessage = undefined;
+    userCategory = undefined;
 }
 /** Base class for failures produced specifically by the Hopper provider. */
 export class HopperError extends AnalysisError {
@@ -148,6 +153,17 @@ export class EvidenceFileError extends AnalysisError {
         this.reason = reason;
     }
 }
+/** Persistent investigation workspace access or CAS validation failed. */
+export class InvestigationWorkspaceError extends AnalysisError {
+    operation;
+    reason;
+    _tag = "InvestigationWorkspaceError";
+    constructor(operation, reason, options) {
+        super(`Investigation workspace ${operation} failed: ${reason}`, options);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
 /** Residual-unknown mutation failed a lifecycle, reference, or CAS invariant. */
 export class UnknownRegistryError extends AnalysisError {
     reason;
@@ -194,9 +210,14 @@ export class HopperRemoteError extends HopperError {
 export class HopperProcessError extends HopperError {
     exitCode;
     _tag = "HopperProcessError";
+    failureCode;
+    userMessage;
     constructor(exitCode) {
         super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
         this.exitCode = exitCode;
+        const failure = hopperStartupFailure(exitCode);
+        this.failureCode = failure?.code;
+        this.userMessage = failure?.message;
     }
 }
 /** Hopper or the repository bridge could not be started. */
@@ -229,54 +250,171 @@ export class BinaryTargetError extends AnalysisError {
 /** Project expected failures into exhaustive, secret-safe caller fields. */
 export const projectAnalysisError = (error) => {
     assertKnownTag(error._tag);
+    const code = error instanceof HopperProcessError ? error.failureCode : undefined;
     return {
-        tag: error._tag,
-        message: error.message,
-        details: safeDetails(error),
+        category: errorCategory(error),
+        message: userMessage(error),
+        ...(code === undefined ? {} : { code }),
     };
 };
-const safeDetails = (error) => {
+const errorCategory = (error) => {
+    if (error._tag === "ProcessCaptureError")
+        return error.userCategory ?? "execution_failure";
+    if (error instanceof HopperRemoteError &&
+        error.diagnosticType === "authorization")
+        return "permission_required";
+    if (error instanceof ArtifactOperationError)
+        return artifactErrorCategory(error.reason);
+    if (error instanceof EvidenceFileError && error.reason === "disabled")
+        return "unavailable";
+    if (error instanceof InvestigationWorkspaceError)
+        return investigationWorkspaceCategory(error.reason);
+    return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
+};
+const investigationWorkspaceCategory = (reason) => {
+    if (reason === "disabled" ||
+        reason === "outside-root" ||
+        reason === "not-file")
+        return "unavailable";
+    if (reason === "too-large")
+        return "truncated";
+    if (reason === "invalid-json" || reason === "integrity")
+        return "integrity_mismatch";
+    return "execution_failure";
+};
+const artifactErrorCategory = (reason) => {
+    if (reason === "integrity")
+        return "integrity_mismatch";
+    if (reason === "limit")
+        return "truncated";
+    if (reason === "cancelled")
+        return "cancelled";
+    if (reason === "unavailable")
+        return "unavailable";
+    return "execution_failure";
+};
+const STATIC_ERROR_CATEGORIES = {
+    AnalysisInputError: "invalid_input",
+    AnalysisCapabilityUnavailableError: "unsupported_provider",
+    ProviderSelectionError: "unsupported_provider",
+    EvidenceIntegrityError: "integrity_mismatch",
+    EvidenceLimitError: "truncated",
+    AnalysisCancelledError: "cancelled",
+    HopperCancelledError: "cancelled",
+    AnalysisTimeoutError: "timeout",
+    HopperTimeoutError: "timeout",
+    NoBinaryOpenError: "unavailable",
+    BinaryTargetError: "unavailable",
+};
+const userMessage = (error) => {
     if (error instanceof AnalysisInputError)
-        return { operation: error.operation };
-    if (error instanceof AnalysisOutputError)
-        return { operation: error.operation, reason: error.reason };
-    if (error instanceof AnalysisCapabilityUnavailableError)
-        return {
-            providerId: error.providerId,
-            operation: error.operation,
-            reason: error.reason,
-        };
-    if (error instanceof AnalysisCancelledError)
-        return { operation: error.operation };
-    if (error instanceof AnalysisTimeoutError)
-        return { operation: error.operation, timeoutMs: error.timeoutMs };
-    if (error instanceof ProviderSelectionError)
-        return { operation: error.operation };
-    if (error instanceof ProviderAdapterError)
-        return { providerId: error.providerId, operation: error.operation };
+        return "Analysis input is invalid. Check the arguments and try again.";
+    if (error.userMessage !== undefined)
+        return error.userMessage;
+    if (UNREADABLE_OUTPUT_TAGS.has(error._tag))
+        return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
+    if (UNSUPPORTED_PROVIDER_TAGS.has(error._tag))
+        return "This analysis is unavailable for the current target. Choose another analysis or target.";
+    if (CANCELLED_TAGS.has(error._tag))
+        return "Analysis was cancelled. Start it again when ready.";
+    if (TIMEOUT_TAGS.has(error._tag))
+        return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
+    if (ADAPTER_FAILURE_TAGS.has(error._tag))
+        return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
+    if (START_FAILURE_TAGS.has(error._tag))
+        return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
     if (error instanceof ArtifactOperationError)
-        return {
-            operation: error.operation,
-            reason: error.reason,
-            ...error.artifactDetails,
-        };
+        return artifactMessage(error.reason);
+    if (error instanceof EvidenceIntegrityError)
+        return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
     if (error instanceof EvidenceLimitError)
-        return { limit: error.limit, maximum: error.maximum };
+        return "Evidence is too large for this session. Reduce the evidence set and try again.";
     if (error instanceof EvidenceFileError)
-        return { operation: error.operation, reason: error.reason };
+        return evidenceFileMessage(error.reason);
+    if (error instanceof InvestigationWorkspaceError)
+        return investigationWorkspaceMessage(error.reason);
     if (error instanceof UnknownRegistryError)
-        return { reason: error.reason };
-    if (error instanceof HopperTimeoutError)
-        return { timeoutMs: error.timeoutMs };
-    if (error instanceof HopperRemoteError)
-        return {
-            code: error.code,
-            safeMessage: error.safeMessage,
-            diagnosticType: error.diagnosticType,
-        };
-    if (error instanceof HopperProcessError)
-        return { exitCode: error.exitCode };
-    return {};
+        return "Evidence state changed before the update completed. Refresh the current state and try again.";
+    if (error instanceof ConfigurationError)
+        return "REA configuration is invalid. Run `rea doctor` and fix the reported setting.";
+    if (error instanceof NoBinaryOpenError)
+        return error.message;
+    if (error instanceof BinaryTargetError)
+        return "REA could not open that app or binary. Check that the path exists, is readable, and points to a supported file.";
+    if (error._tag === "ProcessCaptureError")
+        return (error.userMessage ??
+            "Process capture could not complete. Run `rea doctor`, then review capture policy and try again.");
+    return "Analysis could not complete. Run `rea doctor`, then try again.";
+};
+const UNREADABLE_OUTPUT_TAGS = new Set([
+    "AnalysisProtocolError",
+    "AnalysisOutputError",
+    "HopperProtocolError",
+]);
+const UNSUPPORTED_PROVIDER_TAGS = new Set([
+    "AnalysisCapabilityUnavailableError",
+    "ProviderSelectionError",
+]);
+const CANCELLED_TAGS = new Set([
+    "AnalysisCancelledError",
+    "HopperCancelledError",
+]);
+const TIMEOUT_TAGS = new Set([
+    "AnalysisTimeoutError",
+    "HopperTimeoutError",
+]);
+const ADAPTER_FAILURE_TAGS = new Set([
+    "ProviderAdapterError",
+    "HopperRemoteError",
+]);
+const START_FAILURE_TAGS = new Set([
+    "HopperProcessError",
+    "HopperStartError",
+]);
+const artifactMessage = (reason) => {
+    if (reason === "cancelled")
+        return "Artifact operation was cancelled. Start it again when ready.";
+    if (reason === "limit")
+        return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
+    if (reason === "path")
+        return "Artifact path is not allowed. Choose a path inside the artifact and try again.";
+    if (reason === "unavailable")
+        return "Artifact format is not available on this system. Choose another artifact or supported environment.";
+    if (reason === "format" || reason === "integrity")
+        return "Artifact is invalid or has changed. Get a fresh copy and try again.";
+    return "Artifact could not be read or written. Check file access and try again.";
+};
+const evidenceFileMessage = (reason) => {
+    if (reason === "disabled")
+        return "Evidence file access is disabled. Enable an evidence directory or use inline evidence.";
+    if (reason === "outside-root")
+        return "Evidence path is outside the allowed directory. Choose a path inside the configured evidence directory.";
+    if (reason === "not-file")
+        return "Evidence path does not point to a file. Choose an evidence file and try again.";
+    if (reason === "too-large")
+        return "Evidence file is too large. Reduce its size and try again.";
+    if (reason === "exists")
+        return "Evidence file already exists. Choose another path or allow overwrite.";
+    if (reason === "invalid-json")
+        return "Evidence file is not valid JSON. Repair or recreate the file and try again.";
+    return "Evidence file could not be accessed. Check file permissions and try again.";
+};
+const investigationWorkspaceMessage = (reason) => {
+    if (reason === "disabled")
+        return "Investigation workspace access is disabled. Configure a workspace directory and try again.";
+    if (reason === "outside-root")
+        return "Investigation workspace is outside the allowed directory. Choose a configured workspace directory and try again.";
+    if (reason === "not-file")
+        return "Investigation workspace path is not a file. Choose a workspace file and try again.";
+    if (reason === "too-large")
+        return "Investigation workspace is too large. Reduce its size and try again.";
+    if (reason === "invalid-json" || reason === "integrity")
+        return "Investigation workspace is invalid or has changed. Recreate or repair it, then try again.";
+    if (reason === "locked")
+        return "Another investigation update is in progress. Try again when it finishes.";
+    if (reason === "revision-conflict" || reason === "name-conflict")
+        return "Investigation workspace state changed. Refresh the current state and try again.";
+    return "Investigation workspace could not be accessed. Check file permissions and try again.";
 };
 const KNOWN_ERROR_TAGS = {
     AnalysisProtocolError: true,
@@ -292,6 +430,7 @@ const KNOWN_ERROR_TAGS = {
     EvidenceIntegrityError: true,
     EvidenceLimitError: true,
     EvidenceFileError: true,
+    InvestigationWorkspaceError: true,
     UnknownRegistryError: true,
     HopperTimeoutError: true,
     HopperCancelledError: true,

package/dist/domain/evidence.js

@@ -3,7 +3,8 @@ import canonicalize from "canonicalize";
 import { z } from "zod";
 import { jsonValueSchema } from "./jsonValue.js";
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
-const providerSchema = z.object({
+/** Provider identity schema shared by evidence-bearing persistence formats. */
+export const providerSchema = z.object({
     id: z.string().min(1),
     name: z.string().min(1),
     version: z.string().nullable(),
@@ -36,7 +37,8 @@ const subjectSchema = z.object({
     local_path: z.string(),
 });
 /** Source location attached to an evidence observation. */
-const evidenceLocationSchema = z.discriminatedUnion("kind", [
+/** Source-location schema shared by evidence-bearing persistence formats. */
+export const evidenceLocationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("address"), address: z.string().min(1) }),
     z.object({
         kind: z.literal("address-range"),

package/dist/domain/evidenceBundle.js

@@ -66,6 +66,34 @@ export const createEvidenceBundle = (records, unknowns = []) => {
         records: sortedRecords,
     };
 };
+/** Restrict a bundle to records and complete unknown histories for one artifact. */
+export const evidenceBundleForTarget = (bundle, sha256) => {
+    const recordsById = new Map(bundle.records.map((record) => [record.evidence_id, record]));
+    let unknowns = bundle.unknowns.filter(({ scope_digest: scopeDigest }) => scopeDigest === sha256);
+    let changed = true;
+    while (changed) {
+        const ids = new Set(unknowns.map(({ unknown_id: id }) => id));
+        const retained = unknowns.filter((unknown) => unknown.relationships.every(({ unknown_id: id }) => ids.has(id)) &&
+            referencedEvidenceIds(unknown).every((id) => {
+                const record = recordsById.get(id);
+                return (record?.subject?.digest.sha256 === sha256 ||
+                    (unknown.mutation_evidence_ids.includes(id) &&
+                        record?.subject === null &&
+                        record.predicate_type === "rea.residual-unknown-mutation/v1"));
+            }));
+        changed = retained.length !== unknowns.length;
+        unknowns = retained;
+    }
+    const mutationIds = new Set(unknowns.flatMap(({ mutation_evidence_ids: ids }) => ids));
+    return createEvidenceBundle(bundle.records.filter((record) => record.subject?.digest.sha256 === sha256 ||
+        mutationIds.has(record.evidence_id)), unknowns);
+};
+const referencedEvidenceIds = (unknown) => [
+    ...unknown.supporting_evidence_ids,
+    ...unknown.contradicting_evidence_ids,
+    ...unknown.mutation_evidence_ids,
+    ...(unknown.resolution?.evidence_ids ?? []),
+];
 /** Parse records, verify semantic IDs, and reject inconsistent manifests. */
 export const parseEvidenceBundle = (input) => {
     const parsed = evidenceBundleSchema.parse(input);

package/dist/domain/hopperStartupFailure.js

@@ -0,0 +1,55 @@
+const failures = [
+    [
+        70,
+        "private_display_unavailable",
+        "REA could not start its private Linux display. Install Xvfb, then rerun rea doctor.",
+    ],
+    [
+        71,
+        "x11_authorization_failed",
+        "REA could not authorize its private Linux display. Install xauth, then rerun rea doctor.",
+    ],
+    [
+        72,
+        "unsupported_hopper_build",
+        "This Hopper build is not supported for unattended Linux analysis. Unset HOPPER_LAUNCHER_PATH and rerun rea setup --yes --install-hopper, or update REA.",
+    ],
+    [
+        73,
+        "invalid_launch_command",
+        "REA refused an unexpected Hopper launch command. Check HOPPER_LAUNCHER_PATH and rerun rea doctor.",
+    ],
+    [
+        74,
+        "process_ownership_mismatch",
+        "REA could not verify ownership of the launched Hopper process and stopped safely. Close other Hopper sessions and retry.",
+    ],
+    [
+        75,
+        "hopper_exited_during_startup",
+        "Hopper exited before the REA bridge was ready. Run rea doctor and retry the analysis.",
+    ],
+    [
+        76,
+        "unsupported_demo_dialog",
+        "This Hopper demo dialog is not supported for unattended Linux analysis. Update REA or use a supported Hopper build.",
+    ],
+    [
+        77,
+        "unexpected_display_geometry",
+        "REA's private Linux display did not match the validated layout. Close custom display overrides and retry.",
+    ],
+    [
+        78,
+        "x11_input_failed",
+        "REA could not activate Hopper's validated demo control. Install the XTEST runtime, then rerun rea doctor.",
+    ],
+    [
+        79,
+        "runtime_dependency_unavailable",
+        "A Linux demo-session dependency is unavailable. Rerun rea setup --yes --install-hopper, then rea doctor.",
+    ],
+];
+const HOPPER_STARTUP_FAILURES = new Map(failures.map(([exitCode, code, message]) => [exitCode, { code, message }]));
+/** Return the stable public failure associated with a Linux demo adapter exit. */
+export const hopperStartupFailure = (exitCode) => exitCode === null ? undefined : HOPPER_STARTUP_FAILURES.get(exitCode);