refactor(hopper): type the elapsed-deadline guidance as AnalysisTimeoutRecovery (#11135)

This commit is contained in:
morluto authored and GitHub committed 2026-11-15 21:30:20 +08:00
1 parent 0a00d5d6bc
commit 21b5c5460d
1 file changed
+29 -11
+29 -11
View File
@@ -9,6 +9,7 @@ import {
AnalysisUnsupportedTargetError,
AnalysisResourceConstraintError,
AnalysisTimeoutError,
type AnalysisTimeoutRecovery,
} from "./analysisErrorCore.js";
import { ArtifactOperationError } from "./artifactOperationError.js";
import { OPENABLE_APPLE_BUNDLE_TYPES_TEXT } from "./apple/appleBundleTypes.js";
@@ -164,9 +165,7 @@ export const analysisErrorRemediationAction = (
)
return "Use an artifact within the capacity reported in details.detail. Changing output detail or retrying the unchanged input does not remove this boundary.";
if (error instanceof HopperTimeoutError)
return error.operation === undefined
? HOPPER_STARTUP_TIMEOUT_REMEDIATION
: RERUN_HOPPER_INVOCATION;
return hopperTimeoutRecovery(error).remediationAction;
if (error instanceof HopperProcessError)
return error.failureCode !== undefined && error.userMessage !== undefined
? error.userMessage
@@ -621,14 +620,8 @@ const unclassifiedProviderRemediation = (providerId: string): string =>
: "Review the reported details for the provider's reason; REA has no specific recovery for this unclassified failure. Repeating the unchanged request is not expected to succeed.";
const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
if (error instanceof HopperTimeoutError) {
if (error.operation === undefined)
return "REA timed out waiting for Hopper bridge readiness, which includes initial analysis. Hopper may still be analyzing the target or waiting for a loader, demo, or license dialog. Review the captured launcher outcome and resolve retained cleanup before retrying.";
const request = error.operation;
return error.providerState === "busy"
? `Hopper timed out during ${request} while the provider remained busy.`
: `Hopper timed out during ${request} before it started.`;
}
if (error instanceof HopperTimeoutError)
return hopperTimeoutRecovery(error).userMessage;
if (error instanceof HopperProcessError) return hopperProcessMessage(error);
if (error instanceof HopperStartError) {
if (hopperAppleEventsAuthorizationDenied(error.launchRejection))
@@ -643,6 +636,31 @@ const hopperErrorUserMessage = (error: AnalysisError): string | undefined => {
return undefined;
};
/**
* The invocation caller's recovery for an elapsed Hopper deadline: the startup
* deadline (bridge readiness) or one request's deadline.
*/
const hopperTimeoutRecovery = (
error: HopperTimeoutError,
): Required<
Pick<AnalysisTimeoutRecovery, "userMessage" | "remediationAction">
> => {
if (error.operation === undefined)
return {
userMessage:
"REA timed out waiting for Hopper bridge readiness, which includes initial analysis. Hopper may still be analyzing the target or waiting for a loader, demo, or license dialog. Review the captured launcher outcome and resolve retained cleanup before retrying.",
remediationAction: HOPPER_STARTUP_TIMEOUT_REMEDIATION,
};
const request = error.operation;
return {
userMessage:
error.providerState === "busy"
? `Hopper timed out during ${request} while the provider remained busy.`
: `Hopper timed out during ${request} before it started.`,
remediationAction: RERUN_HOPPER_INVOCATION,
};
};
const RESTART_OWNED_PROVIDER =
"Restart the owned provider by calling close_binary, then open the target again and retry.";
const RESTART_UNREACHABLE_HOPPER = `${RESTART_OWNED_PROVIDER} close_binary preserves retained Evidence and Unknown history on this connection; export_evidence_bundle before ending the REA process if you need to resume later.`;