rea-agents 2.0.0 → 2.2.0

package/dist/domain/analysisErrorPresentation.js

@@ -0,0 +1,234 @@
+import { AnalysisInputError, ArtifactOperationError, BinaryTargetError, BrowserObservationError, ConfigurationError, EvidenceFileError, EvidenceIntegrityError, EvidenceLimitError, HopperRemoteError, InvestigationWorkspaceError, NoBinaryOpenError, PermissionRequiredError, ProviderSelectionError, ReplayPlanStaleError, UnknownRegistryError, } from "./errors.js";
+export const analysisErrorRemediationAction = (error) => {
+    if (error instanceof AnalysisInputError)
+        return "Correct the listed arguments and retry.";
+    if (error instanceof ReplayPlanStaleError)
+        return "Review the rebuilt replay plan and explicitly approve its new digest.";
+    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 analysisErrorUserMessage(error);
+};
+export const analysisErrorCategory = (error) => {
+    if (error instanceof ReplayPlanStaleError)
+        return "integrity_mismatch";
+    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)
+        return browserErrorCategory(error.reason);
+    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 browserErrorCategory = (reason) => {
+    if (reason === "payload_limit")
+        return "truncated";
+    if (reason === "target_not_found" ||
+        reason === "target_not_allowed" ||
+        reason === "target_changed" ||
+        reason === "endpoint_unreachable" ||
+        reason === "disconnected")
+        return "unavailable";
+    return "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",
+};
+export const analysisErrorUserMessage = (error) => {
+    if (error instanceof ReplayPlanStaleError)
+        return "The controlled replay plan changed before execution. Refresh the current state and try again.";
+    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;
+    const standardMessage = standardErrorMessage(error._tag);
+    if (standardMessage !== undefined)
+        return standardMessage;
+    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 standardErrorMessage = (tag) => {
+    if (UNREADABLE_OUTPUT_TAGS.has(tag))
+        return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
+    if (UNSUPPORTED_PROVIDER_TAGS.has(tag))
+        return "This analysis is unavailable for the current target. Choose another analysis or target.";
+    if (CANCELLED_TAGS.has(tag))
+        return "Analysis was cancelled. Start it again when ready.";
+    if (TIMEOUT_TAGS.has(tag))
+        return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
+    if (ADAPTER_FAILURE_TAGS.has(tag))
+        return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
+    if (START_FAILURE_TAGS.has(tag))
+        return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
+    return undefined;
+};
+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,
+    ReplayPlanStaleError: true,
+};
+export const assertKnownAnalysisErrorTag = (tag) => {
+    if (KNOWN_ERROR_TAGS[tag] !== true)
+        throw new TypeError("Unknown analysis error tag");
+};

package/dist/domain/analysisErrorProjection.js

@@ -0,0 +1,284 @@
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisTimeoutError, ArtifactOperationError, BinaryTargetError, BrowserObservationError, EvidenceFileError, EvidenceLimitError, EvidenceReferenceError, HopperCancelledError, HopperProcessError, HopperRemoteError, HopperTimeoutError, InvestigationWorkspaceError, PermissionRequiredError, ProviderAdapterError, ProviderSelectionError, ReplayPlanStaleError, UnknownRegistryError, } from "./errors.js";
+import { analysisErrorCategory, analysisErrorRemediationAction, analysisErrorUserMessage, assertKnownAnalysisErrorTag, } from "./analysisErrorPresentation.js";
+/** Project expected failures into exhaustive, secret-safe caller fields. */
+export const projectAnalysisError = (error) => {
+    assertKnownAnalysisErrorTag(error._tag);
+    const code = errorCode(error);
+    const details = errorDetails(error);
+    return {
+        code,
+        category: analysisErrorCategory(error),
+        message: analysisErrorUserMessage(error),
+        retryable: RETRYABLE_CODES.has(code),
+        remediation: {
+            action: analysisErrorRemediationAction(error),
+            restart_required: error instanceof PermissionRequiredError && error.restartRequired,
+            ...(error instanceof PermissionRequiredError
+                ? { elicitation_supported: error.elicitationSupported }
+                : {}),
+        },
+        ...(details === undefined ? {} : { details }),
+    };
+};
+const errorCode = (error) => {
+    if (error instanceof ReplayPlanStaleError)
+        return "plan_stale";
+    if (error instanceof PermissionRequiredError)
+        return "permission_required";
+    if (error instanceof ProviderSelectionError)
+        return error.reason === "provider_unavailable"
+            ? "provider_unavailable"
+            : "capability_unavailable";
+    if (error instanceof BrowserObservationError)
+        return browserErrorCode(error.reason);
+    if (error instanceof ArtifactOperationError)
+        return artifactOperationCode(error);
+    if (error instanceof EvidenceFileError)
+        return evidenceFileCode(error.reason);
+    if (error instanceof InvestigationWorkspaceError)
+        return investigationWorkspaceCode(error.reason);
+    if (error instanceof UnknownRegistryError)
+        return unknownRegistryCode(error.reason);
+    if (error._tag === "ProcessCaptureError")
+        return processCaptureCode(error);
+    return staticErrorCode(error._tag);
+};
+const browserErrorCode = (reason) => {
+    if (reason === "payload_limit")
+        return "truncated";
+    if (reason === "target_not_found" ||
+        reason === "target_not_allowed" ||
+        reason === "target_changed")
+        return "target_unavailable";
+    if (reason === "endpoint_unreachable" || reason === "disconnected")
+        return "provider_unavailable";
+    return "unreadable_output";
+};
+const artifactOperationCode = (error) => {
+    if (error.reason === "integrity" && error.artifactDetails !== undefined)
+        return "artifact_integrity_mismatch";
+    if (error.reason === "limit")
+        return "truncated";
+    if (error.reason === "cancelled")
+        return "cancelled";
+    return "artifact_operation_failed";
+};
+const evidenceFileCode = (reason) => {
+    if (reason === "outside-root")
+        return "outside_approved_root";
+    if (reason === "too-large")
+        return "truncated";
+    if (reason === "disabled")
+        return "capability_unavailable";
+    return "execution_failure";
+};
+const investigationWorkspaceCode = (reason) => {
+    if (reason === "revision-conflict" || reason === "name-conflict")
+        return "revision_conflict";
+    if (reason === "too-large")
+        return "truncated";
+    if (reason === "disabled")
+        return "capability_unavailable";
+    if (reason === "outside-root")
+        return "outside_approved_root";
+    if (reason === "integrity" || reason === "invalid-json")
+        return "evidence_integrity_mismatch";
+    return "execution_failure";
+};
+const unknownRegistryCode = (reason) => {
+    if (reason === "revision-conflict" || reason === "already-exists")
+        return "revision_conflict";
+    if (reason === "limit")
+        return "truncated";
+    if (reason === "integrity")
+        return "evidence_integrity_mismatch";
+    return "execution_failure";
+};
+const processCaptureCode = (error) => {
+    if (error.cleanupIncomplete)
+        return "cleanup_incomplete";
+    if (error.userCategory === "cancelled")
+        return "cancelled";
+    if (error.userCategory === "permission_required")
+        return "permission_required";
+    return "process_capture_failed";
+};
+const STATIC_ERROR_CODES = {
+    AnalysisProtocolError: "unreadable_output",
+    AnalysisOutputError: "unreadable_output",
+    HopperProtocolError: "unreadable_output",
+    AnalysisInputError: "invalid_request",
+    AnalysisCapabilityUnavailableError: "capability_unavailable",
+    AnalysisCancelledError: "cancelled",
+    HopperCancelledError: "cancelled",
+    AnalysisTimeoutError: "provider_timeout",
+    HopperTimeoutError: "provider_timeout",
+    HopperProcessError: "provider_unavailable",
+    HopperStartError: "provider_unavailable",
+    ConfigurationError: "configuration_invalid",
+    NoBinaryOpenError: "target_unavailable",
+    BinaryTargetError: "target_unavailable",
+    EvidenceIntegrityError: "evidence_integrity_mismatch",
+    EvidenceLimitError: "truncated",
+    ProviderAdapterError: "execution_failure",
+    HopperRemoteError: "execution_failure",
+};
+const staticErrorCode = (tag) => {
+    switch (tag) {
+        case "ArtifactOperationError":
+        case "BrowserObservationError":
+        case "EvidenceFileError":
+        case "InvestigationWorkspaceError":
+        case "PermissionRequiredError":
+        case "ProcessCaptureError":
+        case "ProviderSelectionError":
+        case "ReplayPlanStaleError":
+        case "UnknownRegistryError":
+            throw new TypeError(`Unhandled specialized analysis error: ${tag}`);
+        default:
+            return STATIC_ERROR_CODES[tag];
+    }
+};
+const errorDetails = (error) => requestErrorDetails(error) ??
+    artifactStateErrorDetails(error) ??
+    providerErrorDetails(error) ??
+    lifecycleErrorDetails(error);
+const requestErrorDetails = (error) => {
+    if (error instanceof AnalysisInputError && error.issues.length > 0)
+        return {
+            operation: error.operation,
+            issues: error.issues.map((issue) => ({
+                path: [...issue.path],
+                reason: issue.reason,
+                ...(issue.expected === undefined ? {} : { expected: issue.expected }),
+                ...(issue.minimum === undefined ? {} : { minimum: issue.minimum }),
+                ...(issue.maximum === undefined ? {} : { maximum: issue.maximum }),
+            })),
+        };
+    if (error instanceof EvidenceReferenceError)
+        return {
+            evidence_id: error.evidenceId,
+            reason: error.reason,
+            expected: error.expected,
+            actual: error.actual,
+        };
+    if (error instanceof ReplayPlanStaleError)
+        return {
+            approved_plan_digest: error.approvedDigest,
+            actual_plan_digest: error.actualDigest,
+            application_code_admitted: false,
+        };
+    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),
+        };
+    return undefined;
+};
+const artifactStateErrorDetails = (error) => {
+    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 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 };
+    return undefined;
+};
+const providerErrorDetails = (error) => {
+    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 };
+    return undefined;
+};
+const lifecycleErrorDetails = (error) => {
+    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._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([
+    "invalid_request",
+    "provider_timeout",
+    "cancelled",
+    "revision_conflict",
+    "provider_unavailable",
+]);