rea-agents 1.7.0 → 2.1.0

package/dist/domain/errors.js

@@ -1,5 +1,6 @@
 import { hopperStartupFailure, } from "./hopperStartupFailure.js";
 export { hopperStartupFailure };
+export { projectAnalysisError } from "./analysisErrorProjection.js";
 /** Stable tags exposed by safe analysis-error projections. */
 const ANALYSIS_ERROR_TAGS = [
     "AnalysisProtocolError",
@@ -28,6 +29,7 @@ const ANALYSIS_ERROR_TAGS = [
     "NoBinaryOpenError",
     "BinaryTargetError",
     "PermissionRequiredError",
+    "ReplayPlanStaleError",
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
@@ -46,10 +48,12 @@ export class AnalysisProtocolError extends AnalysisError {
 /** Caller input failed provider-neutral application parsing. */
 export class AnalysisInputError extends AnalysisError {
     operation;
+    issues;
     _tag = "AnalysisInputError";
-    constructor(operation, options) {
+    constructor(operation, options, issues = []) {
         super(`Invalid analysis input for ${operation}`, options);
         this.operation = operation;
+        this.issues = issues;
     }
 }
 /** Provider output failed provider-neutral application parsing. */
@@ -196,6 +200,20 @@ export class ArtifactOperationError extends AnalysisError {
 export class EvidenceIntegrityError extends AnalysisError {
     _tag = "EvidenceIntegrityError";
 }
+/** A session Evidence reference is missing or has the wrong semantic identity. */
+export class EvidenceReferenceError extends EvidenceIntegrityError {
+    evidenceId;
+    reason;
+    expected;
+    actual;
+    constructor(evidenceId, reason, expected, actual) {
+        super(`Evidence reference ${reason}: ${evidenceId}`);
+        this.evidenceId = evidenceId;
+        this.reason = reason;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
 /** A bounded evidence ledger cannot accept more records or serialized bytes. */
 export class EvidenceLimitError extends AnalysisError {
     limit;
@@ -314,13 +332,14 @@ export class BinaryTargetError extends AnalysisError {
 }
 /** Exact denied authority used by both CLI and MCP remediation. */
 export class PermissionRequiredError extends AnalysisError {
+    _tag = "PermissionRequiredError";
     requested;
     missing;
     ceiling;
     elicitationSupported;
     restartRequired;
-    _tag = "PermissionRequiredError";
-    constructor(requested, missing, ceiling, elicitationSupported, restartRequired) {
+    constructor(...args) {
+        const [requested, missing, ceiling, elicitationSupported, restartRequired] = args;
         super(`Permission required for ${requested.capability}`);
         this.requested = requested;
         this.missing = missing;
@@ -329,449 +348,14 @@ export class PermissionRequiredError extends AnalysisError {
         this.restartRequired = restartRequired;
     }
 }
-/** Project expected failures into exhaustive, secret-safe caller fields. */
-export const projectAnalysisError = (error) => {
-    assertKnownTag(error._tag);
-    const code = errorCode(error);
-    const details = errorDetails(error);
-    return {
-        code,
-        category: errorCategory(error),
-        message: userMessage(error),
-        retryable: RETRYABLE_CODES.has(code),
-        remediation: {
-            action: remediationAction(error),
-            restart_required: error instanceof PermissionRequiredError && error.restartRequired,
-            ...(error instanceof PermissionRequiredError
-                ? { elicitation_supported: error.elicitationSupported }
-                : {}),
-        },
-        ...(details === undefined ? {} : { details }),
-    };
-};
-const errorCode = (error) => {
-    if (error instanceof PermissionRequiredError)
-        return "permission_required";
-    if (error instanceof ProviderSelectionError &&
-        error.reason === "provider_unavailable")
-        return "provider_unavailable";
-    if (error instanceof BrowserObservationError) {
-        if (error.reason === "payload_limit")
-            return "truncated";
-        if (error.reason === "target_not_found" ||
-            error.reason === "target_not_allowed" ||
-            error.reason === "target_changed")
-            return "target_unavailable";
-        if (error.reason === "endpoint_unreachable" ||
-            error.reason === "disconnected")
-            return "provider_unavailable";
-        return "unreadable_output";
-    }
-    if (error instanceof ArtifactOperationError)
-        return error.reason === "integrity" && error.artifactDetails !== undefined
-            ? "artifact_integrity_mismatch"
-            : error.reason === "limit"
-                ? "truncated"
-                : error.reason === "cancelled"
-                    ? "cancelled"
-                    : "artifact_operation_failed";
-    if (error instanceof EvidenceFileError)
-        return error.reason === "outside-root"
-            ? "outside_approved_root"
-            : error.reason === "too-large"
-                ? "truncated"
-                : error.reason === "disabled"
-                    ? "capability_unavailable"
-                    : "execution_failure";
-    if (error instanceof InvestigationWorkspaceError) {
-        if (error.reason === "revision-conflict" ||
-            error.reason === "name-conflict")
-            return "revision_conflict";
-        if (error.reason === "too-large")
-            return "truncated";
-        if (error.reason === "disabled")
-            return "capability_unavailable";
-        if (error.reason === "outside-root")
-            return "outside_approved_root";
-        if (error.reason === "integrity" || error.reason === "invalid-json")
-            return "evidence_integrity_mismatch";
-        return "execution_failure";
+/** Approved replay commitment no longer matches the immediately rebuilt plan. */
+export class ReplayPlanStaleError extends AnalysisError {
+    approvedDigest;
+    actualDigest;
+    _tag = "ReplayPlanStaleError";
+    constructor(approvedDigest, actualDigest) {
+        super("Controlled replay plan changed before execution");
+        this.approvedDigest = approvedDigest;
+        this.actualDigest = actualDigest;
     }
-    if (error instanceof UnknownRegistryError)
-        return error.reason === "revision-conflict" ||
-            error.reason === "already-exists"
-            ? "revision_conflict"
-            : error.reason === "limit"
-                ? "truncated"
-                : error.reason === "integrity"
-                    ? "evidence_integrity_mismatch"
-                    : "execution_failure";
-    if (error._tag === "ProcessCaptureError")
-        return error.cleanupIncomplete
-            ? "cleanup_incomplete"
-            : error.userCategory === "cancelled"
-                ? "cancelled"
-                : error.userCategory === "permission_required"
-                    ? "permission_required"
-                    : "process_capture_failed";
-    switch (error._tag) {
-        case "AnalysisProtocolError":
-        case "AnalysisOutputError":
-        case "HopperProtocolError":
-            return "unreadable_output";
-        case "AnalysisInputError":
-            return "invalid_request";
-        case "AnalysisCapabilityUnavailableError":
-        case "ProviderSelectionError":
-            return "capability_unavailable";
-        case "AnalysisCancelledError":
-        case "HopperCancelledError":
-            return "cancelled";
-        case "AnalysisTimeoutError":
-        case "HopperTimeoutError":
-            return "provider_timeout";
-        case "HopperProcessError":
-        case "HopperStartError":
-            return "provider_unavailable";
-        case "ConfigurationError":
-            return "configuration_invalid";
-        case "NoBinaryOpenError":
-        case "BinaryTargetError":
-            return "target_unavailable";
-        case "EvidenceIntegrityError":
-            return "evidence_integrity_mismatch";
-        case "EvidenceLimitError":
-            return "truncated";
-        case "ProviderAdapterError":
-        case "HopperRemoteError":
-            return "execution_failure";
-        case "BrowserObservationError":
-            throw new TypeError("Unhandled specialized browser error");
-        case "ArtifactOperationError":
-        case "EvidenceFileError":
-        case "InvestigationWorkspaceError":
-        case "UnknownRegistryError":
-        case "PermissionRequiredError":
-            throw new TypeError("Unhandled specialized analysis error");
-    }
-};
-const errorDetails = (error) => {
-    if (error instanceof PermissionRequiredError)
-        return {
-            capability: error.requested.capability,
-            requested: scopeDetails(error.requested),
-            missing: missingScopeDetails(error.missing),
-            ceiling: error.ceiling === null ? null : scopeDetails(error.ceiling),
-        };
-    if (error instanceof ArtifactOperationError && error.artifactDetails)
-        return {
-            logical_path: error.artifactDetails.logicalPath,
-            declared_sha256: error.artifactDetails.declaredSha256,
-            calculated_sha256: error.artifactDetails.calculatedSha256,
-            unpacked: error.artifactDetails.unpacked,
-        };
-    if (error instanceof ArtifactOperationError)
-        return {
-            operation: error.operation,
-            reason: error.reason,
-            ...(error.reason === "limit" ? { truncated: true } : {}),
-        };
-    if (error instanceof AnalysisCancelledError)
-        return { operation: error.operation, cleanup: "complete" };
-    if (error instanceof HopperCancelledError)
-        return { operation: "hopper", cleanup: "complete" };
-    if (error instanceof AnalysisTimeoutError)
-        return { operation: error.operation, timeout_ms: error.timeoutMs };
-    if (error instanceof HopperTimeoutError)
-        return { operation: "hopper", timeout_ms: error.timeoutMs };
-    if (error instanceof EvidenceLimitError)
-        return { limit: error.limit, maximum: error.maximum, truncated: true };
-    if (error instanceof InvestigationWorkspaceError)
-        return { operation: error.operation, reason: error.reason };
-    if (error instanceof UnknownRegistryError)
-        return { reason: error.reason };
-    if (error instanceof EvidenceFileError)
-        return { operation: error.operation, reason: error.reason };
-    if (error instanceof AnalysisCapabilityUnavailableError)
-        return { provider_id: error.providerId, operation: error.operation };
-    if (error instanceof ProviderSelectionError)
-        return {
-            operation: error.operation,
-            selection_reason: error.reason,
-            requested_provider_id: error.requestedProviderId,
-            candidate_ids: [...error.candidateIds],
-            rejections: error.rejections.map((rejection) => ({
-                provider_id: rejection.providerId,
-                code: rejection.code,
-                reason: rejection.reason,
-                diagnostics: rejection.diagnostics,
-            })),
-        };
-    if (error instanceof ProviderAdapterError)
-        return {
-            provider_id: error.providerId,
-            operation: error.operation,
-            ...(error.diagnostics === undefined
-                ? {}
-                : { diagnostics: error.diagnostics }),
-        };
-    if (error instanceof BrowserObservationError)
-        return { operation: error.operation, reason: error.reason };
-    if (error instanceof HopperRemoteError)
-        return { provider_code: error.code, diagnostic_type: error.diagnosticType };
-    if (error instanceof HopperProcessError && error.failureCode !== undefined)
-        return { failure_code: error.failureCode, exit_code: error.exitCode };
-    if (error._tag === "ProcessCaptureError" && error.cleanupIncomplete)
-        return {
-            cleanup: "incomplete",
-            resources: [...error.cleanupResources],
-        };
-    if (error._tag === "ProcessCaptureError" &&
-        error.userCategory === "cancelled")
-        return { operation: "process_capture", cleanup: "complete" };
-    if (error instanceof BinaryTargetError)
-        return { path: error.path };
-    return undefined;
-};
-const scopeDetails = (scope) => ({
-    capability: scope.capability,
-    roots: [...scope.roots],
-    executables: [...scope.executables],
-    environment_names: [...scope.environment_names],
-    ...(scope.origins === undefined ? {} : { origins: [...scope.origins] }),
-    network: scope.network,
-    mount: scope.mount,
-});
-const missingScopeDetails = (scope) => ({
-    ...(scope.roots === undefined ? {} : { roots: [...scope.roots] }),
-    ...(scope.executables === undefined
-        ? {}
-        : { executables: [...scope.executables] }),
-    ...(scope.environment_names === undefined
-        ? {}
-        : { environment_names: [...scope.environment_names] }),
-    ...(scope.origins === undefined ? {} : { origins: [...scope.origins] }),
-    ...(scope.network === undefined ? {} : { network: scope.network }),
-    ...(scope.mount === undefined ? {} : { mount: scope.mount }),
-});
-const RETRYABLE_CODES = new Set([
-    "provider_timeout",
-    "cancelled",
-    "revision_conflict",
-    "provider_unavailable",
-]);
-const remediationAction = (error) => {
-    if (error instanceof PermissionRequiredError)
-        return error.elicitationSupported
-            ? "Approve the exact missing scope, then retry the operation."
-            : "Add the exact missing scope beneath the administrator ceiling, then retry.";
-    return userMessage(error);
-};
-const errorCategory = (error) => {
-    if (error instanceof PermissionRequiredError)
-        return "permission_required";
-    if (error instanceof ProviderSelectionError &&
-        error.reason === "provider_unavailable")
-        return "unavailable";
-    if (error._tag === "ProcessCaptureError")
-        return error.userCategory ?? "execution_failure";
-    if (error instanceof BrowserObservationError) {
-        if (error.reason === "payload_limit")
-            return "truncated";
-        if (error.reason === "target_not_found" ||
-            error.reason === "target_not_allowed" ||
-            error.reason === "target_changed" ||
-            error.reason === "endpoint_unreachable" ||
-            error.reason === "disconnected")
-            return "unavailable";
-    }
-    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 PermissionRequiredError)
-        return "This operation needs additional local permission. Review the requested scope and remediation.";
-    if (error instanceof AnalysisInputError)
-        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 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 "Evidence is too large for this session. Reduce the evidence set and try again.";
-    if (error instanceof EvidenceFileError)
-        return evidenceFileMessage(error.reason);
-    if (error instanceof InvestigationWorkspaceError)
-        return investigationWorkspaceMessage(error.reason);
-    if (error instanceof UnknownRegistryError)
-        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,
-    AnalysisInputError: true,
-    AnalysisOutputError: true,
-    AnalysisCapabilityUnavailableError: true,
-    AnalysisCancelledError: true,
-    AnalysisTimeoutError: true,
-    ProviderSelectionError: true,
-    ProviderAdapterError: true,
-    BrowserObservationError: true,
-    ArtifactOperationError: true,
-    ProcessCaptureError: true,
-    EvidenceIntegrityError: true,
-    EvidenceLimitError: true,
-    EvidenceFileError: true,
-    InvestigationWorkspaceError: true,
-    UnknownRegistryError: true,
-    HopperTimeoutError: true,
-    HopperCancelledError: true,
-    HopperProtocolError: true,
-    HopperRemoteError: true,
-    HopperProcessError: true,
-    HopperStartError: true,
-    ConfigurationError: true,
-    NoBinaryOpenError: true,
-    BinaryTargetError: true,
-    PermissionRequiredError: true,
-};
-const assertKnownTag = (tag) => {
-    if (KNOWN_ERROR_TAGS[tag] !== true)
-        throw new TypeError("Unknown analysis error tag");
-};
+}