1219 lines
39 KiB
TypeScript
1219 lines
39 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
AnalysisCapabilityUnavailableError,
|
|
AnalysisUnsupportedTargetError,
|
|
AnalysisInputError,
|
|
AnalysisOutputError,
|
|
AnalysisCancelledError,
|
|
AnalysisTimeoutError,
|
|
AnalysisResourceConstraintError,
|
|
} from "./analysisErrorCore.js";
|
|
import { ArtifactOperationError } from "./artifactOperationError.js";
|
|
import {
|
|
BinaryTargetError,
|
|
ConfigurationError,
|
|
} from "./configurationErrors.js";
|
|
import { BrowserObservationError } from "./browserObservationError.js";
|
|
import { EvidenceFileError, EvidenceIntegrityError } from "./evidenceErrors.js";
|
|
import {
|
|
HopperProcessError,
|
|
HopperRemoteError,
|
|
HopperStartError,
|
|
HopperTimeoutError,
|
|
} from "./hopperErrors.js";
|
|
import { ProviderAdapterError } from "./providerAdapterError.js";
|
|
import { UnknownRegistryError } from "./unknownRegistryError.js";
|
|
import { projectAnalysisError } from "./analysisErrorProjection.js";
|
|
import { ProviderSelectionError } from "./providerSelectionError.js";
|
|
import { analysisErrorProjectionSchema } from "../contracts/errorSchemas.js";
|
|
import { nativeCallPartialObservationSchema } from "./native/nativeCallPartialObservation.js";
|
|
|
|
describe("agent recovery metadata", () => {
|
|
it("does not mark deterministic input validation as retryable", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisInputError("extract_firmware", undefined, [
|
|
{ path: ["range", "length"], reason: "missing_argument" },
|
|
]),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "invalid_request",
|
|
retryable: false,
|
|
remediation: {
|
|
action: expect.stringContaining("Do not repeat the unchanged call."),
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected);
|
|
});
|
|
|
|
it("distinguishes deterministic duplicate identities from stale update revisions", () => {
|
|
const duplicate = projectAnalysisError(
|
|
new UnknownRegistryError("already-exists"),
|
|
);
|
|
expect(duplicate).toMatchObject({
|
|
code: "invalid_request",
|
|
category: "invalid_input",
|
|
retryable: false,
|
|
details: { reason: "already-exists" },
|
|
remediation: {
|
|
action: expect.stringContaining("do not repeat record_unknown"),
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.parse(duplicate)).toEqual(duplicate);
|
|
expect(
|
|
projectAnalysisError(new UnknownRegistryError("revision-conflict")),
|
|
).toMatchObject({ code: "revision_conflict", retryable: true });
|
|
});
|
|
|
|
it.each(["history_gap", "revision_chain"] as const)(
|
|
"preserves %s as an integrity failure with producer facts",
|
|
(kind) => {
|
|
const constraint = { kind, unknown_id: `unk_${"0".repeat(64)}` };
|
|
const projected = projectAnalysisError(
|
|
new UnknownRegistryError(constraint, {
|
|
cause: new Error("Unrelated private diagnostic"),
|
|
}),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "evidence_integrity_mismatch",
|
|
retryable: false,
|
|
details: { reason: "integrity", constraint },
|
|
});
|
|
expect(projected.message).toContain(constraint.unknown_id);
|
|
expect(JSON.stringify(projected)).not.toContain(
|
|
"Unrelated private diagnostic",
|
|
);
|
|
expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected);
|
|
},
|
|
);
|
|
|
|
it("keeps retryability for transient conflicts and provider timeouts", () => {
|
|
expect(
|
|
projectAnalysisError(new UnknownRegistryError("revision-conflict")),
|
|
).toMatchObject({ code: "revision_conflict", retryable: true });
|
|
expect(
|
|
projectAnalysisError(
|
|
new AnalysisTimeoutError("inspect_binary_layout", 2500),
|
|
),
|
|
).toMatchObject({ code: "provider_timeout", retryable: true });
|
|
});
|
|
|
|
it("names the input contract for malformed analysis arguments", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisInputError("inspect_analysis_view", undefined, [
|
|
{
|
|
path: ["view", "kind"],
|
|
reason: "invalid_value",
|
|
expected: ["summary", "module"],
|
|
},
|
|
]),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
recovery: {
|
|
kind: "inspect_input_contract",
|
|
operation: "inspect_analysis_view",
|
|
},
|
|
remediation: {
|
|
action:
|
|
"Read the declared input schema or CLI usage for inspect_analysis_view; if using MCP and the catalog may be stale, call tools/list. Correct the listed fields, then retry. Do not repeat the unchanged call.",
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected);
|
|
});
|
|
|
|
it("separates timeout-state inspection from client deadline recovery", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisTimeoutError("inspect_binary_layout", 2_500),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "provider_timeout",
|
|
recovery: {
|
|
kind: "inspect_timeout_state",
|
|
operation: "inspect_binary_layout",
|
|
timeout_ms: 2_500,
|
|
},
|
|
message: expect.stringContaining("server/provider deadline"),
|
|
remediation: {
|
|
action: expect.stringContaining("provider diagnostics"),
|
|
},
|
|
});
|
|
expect(projected.message).toContain("not a client-side timeout");
|
|
expect(projected.remediation.action).not.toContain(
|
|
"raise its tool deadline",
|
|
);
|
|
expect(projected.remediation.action).not.toMatch(
|
|
/declared timeout controls|larger server\/provider budget|without assuming adjustable limits|do not assume adjustable/u,
|
|
);
|
|
expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected);
|
|
});
|
|
});
|
|
|
|
describe("capability failure retry disposition", () => {
|
|
it.each([
|
|
{ options: {}, retryable: false, category: "unsupported_provider" },
|
|
{
|
|
options: { retryable: false },
|
|
retryable: false,
|
|
category: "unsupported_provider",
|
|
},
|
|
{ options: { retryable: true }, retryable: true, category: "unavailable" },
|
|
] as const)(
|
|
"preserves the producer's $retryable disposition",
|
|
({ options, retryable, category }) => {
|
|
const reason = "Native self-test failed with a sharing violation";
|
|
const projected = projectAnalysisError(
|
|
new AnalysisCapabilityUnavailableError(
|
|
"fixture-provider",
|
|
"inspect",
|
|
reason,
|
|
options,
|
|
),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "capability_unavailable",
|
|
category,
|
|
retryable,
|
|
details: { reason },
|
|
});
|
|
if (retryable) {
|
|
expect(projected.message).toBe(
|
|
"Required runtime controls are unavailable for this attempt.",
|
|
);
|
|
expect(projected.remediation.action).toContain(
|
|
"retry the same analysis",
|
|
);
|
|
}
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(
|
|
true,
|
|
);
|
|
},
|
|
);
|
|
|
|
it("preserves a caller-selected message for a retryable failure", () => {
|
|
expect(
|
|
projectAnalysisError(
|
|
new AnalysisCapabilityUnavailableError(
|
|
"fixture-provider",
|
|
"inspect",
|
|
"temporary failure",
|
|
{
|
|
retryable: true,
|
|
userMessage: "Selected runtime diagnostic",
|
|
},
|
|
),
|
|
).message,
|
|
).toBe("Selected runtime diagnostic");
|
|
});
|
|
|
|
it("retains cleanup ownership before allowing a transient operation to retry", () => {
|
|
expect(
|
|
projectAnalysisError(
|
|
new AnalysisCapabilityUnavailableError(
|
|
"fixture-provider",
|
|
"inspect",
|
|
"temporary failure",
|
|
{
|
|
retryable: true,
|
|
cleanup: {
|
|
reason: "owned handle is still live",
|
|
resources: ["native-owner"],
|
|
},
|
|
},
|
|
),
|
|
),
|
|
).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
retryable: false,
|
|
details: {
|
|
cleanup: "incomplete",
|
|
resources: ["native-owner"],
|
|
execution_failure: "capability_unavailable",
|
|
},
|
|
});
|
|
});
|
|
});
|
|
|
|
it("projects a published file receipt alongside retained cleanup failure", () => {
|
|
const projected = projectAnalysisError(
|
|
new EvidenceFileError("write", "io", {
|
|
path: "/tmp/evidence.json",
|
|
published: { path: "/tmp/evidence.json", bytes: 42 },
|
|
cleanup: {
|
|
reason: "staging directory is still owned",
|
|
resources: ["/tmp/.rea-write-abc"],
|
|
},
|
|
cause: new Error("cleanup incomplete"),
|
|
}),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
message:
|
|
"The output file was published, but staging cleanup remains incomplete.",
|
|
remediation: {
|
|
action:
|
|
"Use the published file at details.published_path and resolve the reported staging cleanup failure.",
|
|
},
|
|
details: {
|
|
operation: "write",
|
|
path: "/tmp/evidence.json",
|
|
published: true,
|
|
published_path: "/tmp/evidence.json",
|
|
bytes: 42,
|
|
resources: ["/tmp/.rea-write-abc"],
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(true);
|
|
});
|
|
|
|
const nativeCallPartialObservation = nativeCallPartialObservationSchema.parse({
|
|
kind: "native-call-observation",
|
|
target: {
|
|
path: "/tmp/selected-app",
|
|
sha256: "a".repeat(64),
|
|
architecture: "arm64",
|
|
arguments: [],
|
|
environment: {},
|
|
working_directory: null,
|
|
},
|
|
process: {
|
|
pid: 4242,
|
|
stdout: {
|
|
text: "partial stdout",
|
|
bytes: 13,
|
|
truncated: false,
|
|
complete: false,
|
|
},
|
|
stderr: null,
|
|
other_stops: [],
|
|
},
|
|
debugger: { version: null },
|
|
events: [],
|
|
coverage: { status: "partial", reason: "cancelled" },
|
|
limitations: ["Observation ended before the requested window completed."],
|
|
});
|
|
|
|
const retainedOutput = {
|
|
stdout: "selected output\u0000",
|
|
stderr: "upstream warning",
|
|
truncated: true,
|
|
};
|
|
|
|
it("distinguishes unsupported target formats from unavailable provider capabilities", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisUnsupportedTargetError(
|
|
"inspect_evm_interface",
|
|
"/selected/runtime.hex",
|
|
"EOF-style EF00 container is unsupported.",
|
|
{ capturedOutput: retainedOutput },
|
|
),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "unsupported_target",
|
|
category: "unsupported_target",
|
|
retryable: false,
|
|
details: {
|
|
operation: "inspect_evm_interface",
|
|
path: "/selected/runtime.hex",
|
|
reason: "EOF-style EF00 container is unsupported.",
|
|
captured_output: retainedOutput,
|
|
},
|
|
});
|
|
expect(projected.message).toContain("EF00");
|
|
expect(projected.remediation.action).toContain("target format");
|
|
expect(projected.remediation.action).not.toContain("doctor");
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(true);
|
|
});
|
|
|
|
it("keeps a refusing provider's recovery on a target selection failure", () => {
|
|
const selection = {
|
|
reason: "target_unsupported" as const,
|
|
requestedProviderId: "ghidra",
|
|
candidateIds: ["ghidra"],
|
|
userMessage: "Unsupported target: the configured extension is x86-64 only.",
|
|
};
|
|
expect(
|
|
projectAnalysisError(
|
|
new ProviderSelectionError({
|
|
...selection,
|
|
remediationAction: "Omit the extension setting for this target.",
|
|
}),
|
|
),
|
|
).toMatchObject({
|
|
code: "capability_unavailable",
|
|
message: selection.userMessage,
|
|
remediation: { action: "Omit the extension setting for this target." },
|
|
details: { selection_reason: "target_unsupported" },
|
|
});
|
|
expect(
|
|
projectAnalysisError(new ProviderSelectionError(selection)).remediation
|
|
.action,
|
|
).toBe(selection.userMessage);
|
|
});
|
|
|
|
it.each([false, true])(
|
|
"marks occupied capacity retryable only while cleanup is confirmed: %s",
|
|
(cleanupIncomplete) => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisResourceConstraintError(
|
|
"inspect_sqlite_database",
|
|
"capacity",
|
|
"Inspection slots are occupied",
|
|
{ max_concurrent_inspections: 2 },
|
|
cleanupIncomplete
|
|
? {
|
|
cleanup: {
|
|
reason: "Snapshot removal denied",
|
|
resources: ["/private/snapshot"],
|
|
},
|
|
}
|
|
: undefined,
|
|
),
|
|
);
|
|
expect(projected.retryable).toBe(!cleanupIncomplete);
|
|
expect(projected.code).toBe(
|
|
cleanupIncomplete ? "cleanup_incomplete" : "resource_constraint",
|
|
);
|
|
expect(projected.details).toMatchObject({
|
|
resource: "capacity",
|
|
reported_limits: { max_concurrent_inspections: 2 },
|
|
});
|
|
expect(projected.remediation.action).toContain("Wait");
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(
|
|
true,
|
|
);
|
|
},
|
|
);
|
|
|
|
it.each([
|
|
["memory", null],
|
|
["memory", { address_space_bytes: 67108864 }],
|
|
["cpu", null],
|
|
["cpu", { cpu_seconds: 1 }],
|
|
["file-size", null],
|
|
["file-size", { file_size_bytes: 1024 }],
|
|
["transport", { result_budget_bytes: 10485760 }],
|
|
] as const)(
|
|
"projects reported %s constraints with observed or unknown limits: %j",
|
|
(resource, limits) => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisResourceConstraintError(
|
|
"inspect_binary_layout",
|
|
resource,
|
|
resource === "memory"
|
|
? "Memory allocation failed; exact cause unknown."
|
|
: "Observed SIGXCPU; exact signal cause unknown.",
|
|
limits,
|
|
{ capturedOutput: retainedOutput },
|
|
),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "resource_constraint",
|
|
category: "resource_constraint",
|
|
retryable: false,
|
|
details: {
|
|
resource,
|
|
reported_limits: limits,
|
|
captured_output: retainedOutput,
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(
|
|
true,
|
|
);
|
|
},
|
|
);
|
|
it.each([
|
|
new AnalysisInputError("inspect", { capturedOutput: retainedOutput }),
|
|
new AnalysisOutputError("inspect", "invalid reply", {
|
|
capturedOutput: retainedOutput,
|
|
}),
|
|
new AnalysisCapabilityUnavailableError(
|
|
"provider",
|
|
"inspect",
|
|
"unsupported profile",
|
|
{ capturedOutput: retainedOutput },
|
|
),
|
|
new AnalysisCancelledError("inspect", { capturedOutput: retainedOutput }),
|
|
new AnalysisTimeoutError("inspect", 30, { capturedOutput: retainedOutput }),
|
|
new ProviderSelectionError({
|
|
operation: "inspect",
|
|
reason: "provider_unavailable",
|
|
requestedProviderId: "provider",
|
|
candidateIds: [],
|
|
capturedOutput: retainedOutput,
|
|
}),
|
|
])(
|
|
"retains captured output without changing the typed primary failure: $._tag",
|
|
(failure) => {
|
|
expect(projectAnalysisError(failure).details?.captured_output).toEqual(
|
|
retainedOutput,
|
|
);
|
|
},
|
|
);
|
|
|
|
it.each([
|
|
new AnalysisCancelledError("observe_native_calls", {
|
|
cleanup: {
|
|
reason: "target process termination could not be verified",
|
|
resources: ["native-target:4242"],
|
|
},
|
|
}),
|
|
new AnalysisTimeoutError("observe_native_calls", 65_000, {
|
|
cleanup: {
|
|
reason: "target process identity was unavailable",
|
|
resources: ["native-target:4242"],
|
|
},
|
|
}),
|
|
])("retains incomplete cleanup for lifecycle failures: $._tag", (failure) => {
|
|
expect(projectAnalysisError(failure)).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
details: {
|
|
cleanup: "incomplete",
|
|
cleanup_reason: expect.any(String),
|
|
resources: ["native-target:4242"],
|
|
},
|
|
});
|
|
});
|
|
|
|
it("retains the original failure tag and code when cleanup is incomplete", () => {
|
|
const error = new EvidenceIntegrityError(
|
|
"The launched native target did not match its selected digest",
|
|
{
|
|
cleanup: {
|
|
reason: "target survivor identity could not be verified",
|
|
resources: ["native-target:4242"],
|
|
},
|
|
},
|
|
);
|
|
expect(error._tag).toBe("EvidenceIntegrityError");
|
|
expect(projectAnalysisError(error)).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
category: "integrity_mismatch",
|
|
details: {
|
|
cleanup: "incomplete",
|
|
cleanup_reason: "target survivor identity could not be verified",
|
|
resources: ["native-target:4242"],
|
|
execution_failure: "evidence_integrity_mismatch",
|
|
},
|
|
});
|
|
});
|
|
|
|
it("projects native partial observations through healthy cancellation failures", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisCancelledError("observe_native_calls", {
|
|
partialObservation: nativeCallPartialObservation,
|
|
}),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "cancelled",
|
|
details: {
|
|
operation: "observe_native_calls",
|
|
cleanup: "complete",
|
|
partial_observation: nativeCallPartialObservation,
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(true);
|
|
});
|
|
|
|
it("retains native partial observations and cleanup uncertainty on provider failures", () => {
|
|
const projected = projectAnalysisError(
|
|
new ProviderAdapterError("native-lldb", "observe_native_calls", {
|
|
partialObservation: nativeCallPartialObservation,
|
|
cleanup: {
|
|
reason: "target process termination could not be verified",
|
|
resources: ["native-target:4242"],
|
|
},
|
|
}),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
details: {
|
|
provider_id: "native-lldb",
|
|
operation: "observe_native_calls",
|
|
cleanup: "incomplete",
|
|
cleanup_reason: "target process termination could not be verified",
|
|
resources: ["native-target:4242"],
|
|
execution_failure: "execution_failure",
|
|
partial_observation: nativeCallPartialObservation,
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(true);
|
|
});
|
|
|
|
describe("analysis error projection: browser provider failures", () => {
|
|
it("explains the service-worker policy refusal and names its recovery", () => {
|
|
const projected = projectAnalysisError(
|
|
new BrowserObservationError(
|
|
"capture_browser_scenario",
|
|
"service_worker_blocked",
|
|
),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "target_unavailable",
|
|
category: "unavailable",
|
|
retryable: false,
|
|
message: expect.stringContaining("service-worker policy is block"),
|
|
remediation: {
|
|
action: expect.stringContaining("environment.service_workers to allow"),
|
|
},
|
|
details: {
|
|
operation: "capture_browser_scenario",
|
|
reason: "service_worker_blocked",
|
|
},
|
|
});
|
|
});
|
|
|
|
it("projects the primary browser failure alongside incomplete cleanup", () => {
|
|
const projected = projectAnalysisError(
|
|
new BrowserObservationError(
|
|
"observe_javascript_runtime",
|
|
"cleanup_failed",
|
|
{
|
|
cause: new AggregateError([
|
|
new BrowserObservationError(
|
|
"observe_javascript_runtime",
|
|
"target_changed",
|
|
),
|
|
new Error("socket close failed"),
|
|
]),
|
|
},
|
|
),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
details: {
|
|
operation: "observe_javascript_runtime",
|
|
reason: "cleanup_failed",
|
|
cleanup: "incomplete",
|
|
resources: ["browser_transport"],
|
|
primary_reason: "target_changed",
|
|
},
|
|
});
|
|
});
|
|
|
|
it("keeps producer facts when a browser failure is attributed to another operation", () => {
|
|
const partial = { kind: "browser-test-partial" } as never;
|
|
const original = new BrowserObservationError(
|
|
"inspect_web_page",
|
|
"cleanup_failed",
|
|
{
|
|
detail: "Target page-1 closed while REA released its session.",
|
|
remediationAction: "Release session page-1, then retry.",
|
|
cleanup: { reason: "socket close failed", resources: ["page-1"] },
|
|
diagnostics: { endpoint: "loopback" },
|
|
partialObservation: partial,
|
|
cause: new AggregateError([
|
|
new BrowserObservationError("inspect_web_page", "target_changed"),
|
|
new Error("socket close failed"),
|
|
]),
|
|
},
|
|
);
|
|
const relabelled = original.forOperation("capture_web_screenshot");
|
|
|
|
expect(relabelled).toMatchObject({
|
|
operation: "capture_web_screenshot",
|
|
reason: "cleanup_failed",
|
|
cause: original.cause,
|
|
diagnostics: { endpoint: "loopback" },
|
|
partialObservation: partial,
|
|
});
|
|
const { details, ...projected } = projectAnalysisError(relabelled);
|
|
const { details: originalDetails, ...originalProjected } =
|
|
projectAnalysisError(original);
|
|
expect(projected).toEqual(originalProjected);
|
|
expect(projected).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
message: "Target page-1 closed while REA released its session.",
|
|
remediation: { action: "Release session page-1, then retry." },
|
|
});
|
|
expect(details).toEqual({
|
|
...originalDetails,
|
|
operation: "capture_web_screenshot",
|
|
});
|
|
expect(details).toMatchObject({
|
|
resources: ["page-1"],
|
|
primary_reason: "target_changed",
|
|
});
|
|
});
|
|
|
|
it("derives default browser guidance for the attributed operation", () => {
|
|
const original = new BrowserObservationError(
|
|
"inspect_web_page",
|
|
"target_not_found",
|
|
);
|
|
expect(original.forOperation("inspect_web_page")).toBe(original);
|
|
|
|
const relabelled = original.forOperation("discover_webmcp_tools");
|
|
const projected = projectAnalysisError(relabelled);
|
|
expect(projected).toMatchObject({
|
|
code: "target_unavailable",
|
|
message: expect.stringMatching(/^discover_webmcp_tools could not find/),
|
|
details: {
|
|
operation: "discover_webmcp_tools",
|
|
reason: "target_not_found",
|
|
},
|
|
});
|
|
expect(projected.message).not.toContain("inspect_web_page");
|
|
expect(
|
|
projectAnalysisError(
|
|
new BrowserObservationError("inspect_web_page", "timeout").forOperation(
|
|
"observe_web_session",
|
|
),
|
|
),
|
|
).toMatchObject({
|
|
code: projectAnalysisError(
|
|
new BrowserObservationError("observe_web_session", "timeout"),
|
|
).code,
|
|
details: { operation: "observe_web_session", reason: "timeout" },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("analysis error projection: Hopper provider failures", () => {
|
|
it("reports a timed-out active Hopper request and actionable retry guidance", () => {
|
|
const projected = projectAnalysisError(
|
|
new HopperTimeoutError(30_000, "trace_feature", 42, "busy"),
|
|
);
|
|
|
|
expect(projected).toMatchObject({
|
|
code: "provider_timeout",
|
|
category: "timeout",
|
|
retryable: true,
|
|
details: {
|
|
stage: "analysis",
|
|
operation: "trace_feature",
|
|
request_id: 42,
|
|
provider_state: "busy",
|
|
timeout_ms: 30_000,
|
|
},
|
|
});
|
|
expect(projected.message).toContain("binary_session.analysis_activity");
|
|
expect(projected.remediation.action).toContain(
|
|
"wait for the active Hopper request",
|
|
);
|
|
});
|
|
|
|
it("identifies the REA session that already owns a Hopper target", () => {
|
|
const error = new HopperStartError({
|
|
ownerRunId: "session-owner",
|
|
userMessage:
|
|
"This Hopper target is already open in REA session session-owner. Use that REA session or close it before opening this target again.",
|
|
});
|
|
expect(projectAnalysisError(error)).toMatchObject({
|
|
category: "unavailable",
|
|
message: expect.stringContaining("session-owner"),
|
|
remediation: {
|
|
action: expect.stringContaining(
|
|
"Use the active REA session session-owner",
|
|
),
|
|
},
|
|
});
|
|
});
|
|
|
|
it("retains the Hopper request and provider diagnostic on a remote failure", () => {
|
|
expect(
|
|
projectAnalysisError(
|
|
new HopperRemoteError(
|
|
7,
|
|
"Hopper analysis failed in the selected document",
|
|
{
|
|
diagnosticType: "bridge_exception",
|
|
operation: "trace_feature",
|
|
requestId: 43,
|
|
},
|
|
),
|
|
),
|
|
).toMatchObject({
|
|
code: "execution_failure",
|
|
details: {
|
|
stage: "analysis",
|
|
provider_code: 7,
|
|
diagnostic_type: "bridge_exception",
|
|
operation: "trace_feature",
|
|
request_id: 43,
|
|
},
|
|
message: expect.stringContaining("Hopper analysis failed"),
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("analysis error projection: detached provider diagnostics", () => {
|
|
it.each(["adapter", "cancelled", "timeout"])(
|
|
"preserves detached, actionable diagnostics for %s errors",
|
|
(kind) => {
|
|
const diagnostics = {
|
|
runtime_root: "/tmp/rea-ghidra-fixture",
|
|
profile_digest: "a".repeat(64),
|
|
exit_code: 1,
|
|
};
|
|
const error =
|
|
kind === "adapter"
|
|
? new ProviderAdapterError("ghidra", "health", { diagnostics })
|
|
: kind === "cancelled"
|
|
? new AnalysisCancelledError("health", { diagnostics })
|
|
: new AnalysisTimeoutError("health", 250, { diagnostics });
|
|
|
|
expect(error.diagnostics).not.toBe(diagnostics);
|
|
expect(projectAnalysisError(error)).toMatchObject({
|
|
details: {
|
|
...(kind === "adapter" ? { provider_id: "ghidra" } : {}),
|
|
operation: "health",
|
|
diagnostics,
|
|
},
|
|
});
|
|
diagnostics.exit_code = 2;
|
|
expect(error.diagnostics?.exit_code).toBe(1);
|
|
},
|
|
);
|
|
});
|
|
|
|
describe("analysis error projection: Hopper startup failures", () => {
|
|
it("maps the Linux startup compatibility exit codes without host internals", () => {
|
|
const expected = [
|
|
[70, "private_display_unavailable"],
|
|
[71, "x11_authorization_failed"],
|
|
[72, "unsupported_hopper_build"],
|
|
[73, "invalid_launch_command"],
|
|
[74, "process_ownership_mismatch"],
|
|
[75, "hopper_exited_during_startup"],
|
|
[76, "unsupported_demo_dialog"],
|
|
[77, "unexpected_display_geometry"],
|
|
[78, "x11_input_failed"],
|
|
[79, "runtime_dependency_unavailable"],
|
|
[80, "x11_socket_directory_unusable"],
|
|
] as const;
|
|
|
|
for (const [exitCode, code] of expected) {
|
|
const projected = projectAnalysisError(new HopperProcessError(exitCode));
|
|
expect(projected).toMatchObject({
|
|
code: "provider_unavailable",
|
|
details: { failure_code: code, exit_code: exitCode },
|
|
});
|
|
expect(projected.message).toMatch(/\S/u);
|
|
expect(JSON.stringify(projected)).not.toContain("/proc/");
|
|
}
|
|
});
|
|
});
|
|
|
|
describe("analysis error projection: retry guidance", () => {
|
|
it.each([
|
|
[
|
|
"unreadable output",
|
|
new AnalysisOutputError("inspect_firmware_regions", "report missing"),
|
|
"unreadable_output",
|
|
],
|
|
[
|
|
"adapter failure",
|
|
new ProviderAdapterError("firmware", "inspect_firmware_regions"),
|
|
"execution_failure",
|
|
],
|
|
[
|
|
"Hopper remote failure",
|
|
new HopperRemoteError(7, "Hopper analysis failed", {
|
|
diagnosticType: "bridge_exception",
|
|
operation: "trace_feature",
|
|
}),
|
|
"execution_failure",
|
|
],
|
|
])(
|
|
"does not recommend an unchanged retry for non-retryable %s",
|
|
(_name, error, code) => {
|
|
const projected = projectAnalysisError(error);
|
|
|
|
expect(projected).toMatchObject({ code, retryable: false });
|
|
for (const text of [projected.message, projected.remediation.action])
|
|
expect(text).not.toMatch(/\bretry\b/iu);
|
|
},
|
|
);
|
|
});
|
|
|
|
describe("analysis error projection: caller contract", () => {
|
|
it("preserves the reported output constraint without exposing its internal cause", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisOutputError(
|
|
"extract_firmware",
|
|
"Report exceeded the declared byte budget",
|
|
{ cause: new Error("private internal cause") },
|
|
),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "unreadable_output",
|
|
details: {
|
|
operation: "extract_firmware",
|
|
reason: "Report exceeded the declared byte budget",
|
|
},
|
|
});
|
|
expect(JSON.stringify(projected)).not.toContain("private internal cause");
|
|
});
|
|
it("maps representative failures without exposing causes", () => {
|
|
const secretCause = new Error("secret-token");
|
|
const projected = [
|
|
projectAnalysisError(
|
|
new AnalysisInputError("overview", { cause: secretCause }),
|
|
),
|
|
projectAnalysisError(
|
|
new AnalysisCapabilityUnavailableError("fixture", "overview", "absent"),
|
|
),
|
|
projectAnalysisError(
|
|
new BinaryTargetError("/local/targets/app", "invalid", {
|
|
cause: secretCause,
|
|
}),
|
|
),
|
|
];
|
|
|
|
expect(projected.map(({ code }) => code)).toEqual([
|
|
"invalid_request",
|
|
"capability_unavailable",
|
|
"target_unavailable",
|
|
]);
|
|
expect(projected[1]).toMatchObject({
|
|
category: "unsupported_provider",
|
|
message:
|
|
"This analysis is unavailable for the current target. Choose another analysis or target.",
|
|
details: {
|
|
provider_id: "fixture",
|
|
operation: "overview",
|
|
reason: "absent",
|
|
},
|
|
});
|
|
expect(projected[2]).toMatchObject({
|
|
details: { path: "/local/targets/app" },
|
|
});
|
|
expect(JSON.stringify(projected)).not.toContain("secret-token");
|
|
});
|
|
|
|
it.each(["EACCES", "EPERM"] as const)(
|
|
"reports a target the host refused to read (%s) as access_denied",
|
|
(systemCode) => {
|
|
const denied = Object.assign(new Error("denied"), { code: systemCode });
|
|
const reason = `permission denied while reading target: ${systemCode}`;
|
|
expect(
|
|
projectAnalysisError(
|
|
new BinaryTargetError("/local/targets/app", reason, {
|
|
cause: denied,
|
|
}),
|
|
),
|
|
).toMatchObject({
|
|
code: "access_denied",
|
|
category: "unavailable",
|
|
retryable: false,
|
|
remediation: {
|
|
action:
|
|
"Check the current process's read access to the selected path. Retry with a readable local file.",
|
|
},
|
|
details: {
|
|
path: "/local/targets/app",
|
|
reason,
|
|
system_code: systemCode,
|
|
boundary: "filesystem-read",
|
|
},
|
|
});
|
|
expect(
|
|
projectAnalysisError(
|
|
new BinaryTargetError("/local/targets/app", "missing", {
|
|
cause: Object.assign(new Error("missing"), { code: "ENOENT" }),
|
|
}),
|
|
),
|
|
).toMatchObject({ code: "target_unavailable" });
|
|
},
|
|
);
|
|
|
|
it("uses explicit capability recovery while retaining the constraint", () => {
|
|
const projected = projectAnalysisError(
|
|
new AnalysisCapabilityUnavailableError(
|
|
"fixture",
|
|
"capture",
|
|
"host constraint",
|
|
{
|
|
userMessage: "Use the supported host workflow.",
|
|
cause: new Error("private internal cause"),
|
|
},
|
|
),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "capability_unavailable",
|
|
category: "unsupported_provider",
|
|
message: "Use the supported host workflow.",
|
|
details: {
|
|
provider_id: "fixture",
|
|
operation: "capture",
|
|
reason: "host constraint",
|
|
},
|
|
});
|
|
expect(JSON.stringify(projected)).not.toContain("private internal cause");
|
|
});
|
|
|
|
it("preserves exact artifact-integrity coordinates", () => {
|
|
expect(
|
|
projectAnalysisError(
|
|
new ArtifactOperationError("inventory_artifact", "integrity", {
|
|
logicalPath: "main.js",
|
|
declaredSha256: "a".repeat(64),
|
|
calculatedSha256: "b".repeat(64),
|
|
unpacked: true,
|
|
}),
|
|
),
|
|
).toMatchObject({
|
|
category: "integrity_mismatch",
|
|
details: {
|
|
logical_path: "main.js",
|
|
declared_sha256: "a".repeat(64),
|
|
calculated_sha256: "b".repeat(64),
|
|
unpacked: true,
|
|
},
|
|
});
|
|
});
|
|
|
|
it("gives missing residual unknowns lookup-specific remediation", () => {
|
|
expect(
|
|
projectAnalysisError(new UnknownRegistryError("not-found")),
|
|
).toMatchObject({
|
|
code: "execution_failure",
|
|
message:
|
|
"The requested residual unknown does not exist in this session. Check the unknown_id and try again.",
|
|
remediation: {
|
|
action:
|
|
"Check that the unknown_id belongs to this session, then retry.",
|
|
},
|
|
details: { reason: "not-found" },
|
|
});
|
|
});
|
|
});
|
|
|
|
describe("analysis error projection: operational diagnostics", () => {
|
|
it("distinguishes an observed Hopper exit from an undetermined provider failure", () => {
|
|
const exited = projectAnalysisError(
|
|
new HopperProcessError(7, { operation: "search_strings", requestId: 4 }),
|
|
);
|
|
expect(exited).toMatchObject({
|
|
code: "provider_unavailable",
|
|
retryable: true,
|
|
details: {
|
|
stage: "analysis",
|
|
provider_state: "exited",
|
|
retry_action: "restart_provider",
|
|
operation: "search_strings",
|
|
request_id: 4,
|
|
exit_code: 7,
|
|
},
|
|
});
|
|
expect(exited.message).not.toContain("Run `rea doctor`, then try again.");
|
|
expect(exited.remediation.action).toContain("Restart the owned provider");
|
|
|
|
const unknown = projectAnalysisError(
|
|
new HopperProcessError(null, {
|
|
operation: "search_strings",
|
|
requestId: 5,
|
|
}),
|
|
);
|
|
expect(unknown.details).toMatchObject({
|
|
stage: "analysis",
|
|
provider_state: "unknown",
|
|
retry_action: "unknown",
|
|
operation: "search_strings",
|
|
request_id: 5,
|
|
exit_code: null,
|
|
});
|
|
expect(unknown.message).toContain("could not determine");
|
|
expect(unknown.message).not.toContain("stopped");
|
|
expect(unknown.remediation.action).toContain("provider_operation_health");
|
|
|
|
const unreachable = projectAnalysisError(
|
|
new HopperProcessError(null, {
|
|
operation: "search_strings",
|
|
providerState: "unreachable",
|
|
}),
|
|
);
|
|
expect(unreachable.message).toContain(
|
|
"If Hopper may have exited, call export_evidence_bundle before close_binary",
|
|
);
|
|
expect(unreachable.message).toContain("closing clears retained records");
|
|
expect(unreachable.remediation.action).toContain("export_evidence_bundle");
|
|
});
|
|
});
|
|
|
|
describe("analysis error projection: evidence files", () => {
|
|
it.each([
|
|
["read", "missing", "invalid_request", "invalid_input"],
|
|
["read", "not-file", "invalid_request", "invalid_input"],
|
|
["write", "missing", "invalid_request", "invalid_input"],
|
|
["write", "exists", "invalid_request", "invalid_input"],
|
|
["write", "path-limit", "resource_constraint", "resource_constraint"],
|
|
[
|
|
"read",
|
|
"invalid-json",
|
|
"evidence_integrity_mismatch",
|
|
"execution_failure",
|
|
],
|
|
["read", "io", "execution_failure", "execution_failure"],
|
|
] as const)(
|
|
"classifies a %s %s evidence file by who can correct it",
|
|
(operation, reason, code, category) => {
|
|
const projected = projectAnalysisError(
|
|
new EvidenceFileError(operation, reason, { path: "/selected.json" }),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code,
|
|
category,
|
|
details: { operation, reason, path: "/selected.json" },
|
|
});
|
|
expect(analysisErrorProjectionSchema.parse(projected)).toEqual(projected);
|
|
},
|
|
);
|
|
});
|
|
|
|
it("retains the primary failure and both cleanup reports after a secondary failure", () => {
|
|
const callerReason = { caller: "stop" };
|
|
const primary = new AnalysisCancelledError("execute_rizin_command", {
|
|
cause: callerReason,
|
|
capturedOutput: {
|
|
stdout: "partial",
|
|
stderr: "diagnostic",
|
|
truncated: false,
|
|
},
|
|
cleanup: { reason: "writer remains", resources: ["writer"] },
|
|
});
|
|
const secondary = new AnalysisOutputError("open_binary", "cannot rebind", {
|
|
cleanup: { reason: "provider remains", resources: ["provider", "writer"] },
|
|
});
|
|
const enriched = primary.retainSecondaryFailure(secondary, {
|
|
rebind_error: projectAnalysisError(secondary),
|
|
});
|
|
expect(enriched).toBe(primary);
|
|
expect(enriched._tag).toBe("AnalysisCancelledError");
|
|
expect(enriched.cause).toBe(callerReason);
|
|
expect(enriched.secondaryFailures).toEqual([secondary]);
|
|
expect(projectAnalysisError(enriched)).toMatchObject({
|
|
code: "cleanup_incomplete",
|
|
details: {
|
|
execution_failure: "cancelled",
|
|
resources: ["writer"],
|
|
cleanup_reason: "writer remains",
|
|
captured_output: { stdout: "partial", stderr: "diagnostic" },
|
|
diagnostics: { rebind_error: { code: "cleanup_incomplete" } },
|
|
},
|
|
});
|
|
});
|
|
|
|
it("retains secondary failures when the primary error has no cause", () => {
|
|
const primary = new AnalysisCancelledError("execute_rizin_command");
|
|
const secondary = new AnalysisOutputError("open_binary", "cannot rebind");
|
|
|
|
primary.retainSecondaryFailure(secondary, {});
|
|
|
|
expect(primary.cause).toBeUndefined();
|
|
expect(primary.secondaryFailures).toEqual([secondary]);
|
|
});
|
|
|
|
it.each([false, true])(
|
|
"preserves producer capability recovery with retryable=%s",
|
|
(retryable) => {
|
|
const recovery =
|
|
"Choose an explicit disposition, then retry the same session.";
|
|
const projected = projectAnalysisError(
|
|
new AnalysisCapabilityUnavailableError("fixture", "close", "live state", {
|
|
retryable,
|
|
remediationAction: recovery,
|
|
}),
|
|
);
|
|
expect(projected).toMatchObject({
|
|
code: "capability_unavailable",
|
|
retryable,
|
|
remediation: { action: recovery },
|
|
details: {
|
|
provider_id: "fixture",
|
|
operation: "close",
|
|
reason: "live state",
|
|
},
|
|
});
|
|
expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(
|
|
true,
|
|
);
|
|
},
|
|
);
|
|
|
|
it("retains Hopper startup diagnostics beside generic and secondary context", () => {
|
|
const diagnostic = {
|
|
component: "hopper_private_display",
|
|
operation: "launch",
|
|
reason: "fixture_denial",
|
|
socket_directory: "/tmp/.X11-unix",
|
|
socket_directory_mode: null,
|
|
mount_read_only: null,
|
|
effective_socket_directory_mode: null,
|
|
effective_mount_read_only: null,
|
|
wsl: false,
|
|
strategy: "unavailable",
|
|
fallback_reason: null,
|
|
xvfb_stderr_bytes: 0,
|
|
status: "error",
|
|
failure_code: "private_display_unavailable",
|
|
} as const;
|
|
expect(
|
|
projectAnalysisError(new HopperProcessError(null, { diagnostic })).details
|
|
?.diagnostics,
|
|
).toEqual(diagnostic);
|
|
const generic = { caller_context: "retained" };
|
|
expect(
|
|
projectAnalysisError(
|
|
new HopperProcessError(null, { diagnostic, diagnostics: generic }),
|
|
),
|
|
).toMatchObject({
|
|
code: "provider_unavailable",
|
|
details: { diagnostics: generic, provider_diagnostics: diagnostic },
|
|
});
|
|
const secondary = new HopperProcessError(null, {
|
|
diagnostic,
|
|
}).retainSecondaryFailure(new HopperProcessError(null), {
|
|
retirement_error: "retained",
|
|
});
|
|
expect(projectAnalysisError(secondary).details).toMatchObject({
|
|
provider_diagnostics: diagnostic,
|
|
diagnostics: { retirement_error: "retained" },
|
|
});
|
|
});
|
|
|
|
it("does not offer entry-policy retries for integrity refusals without a declared-versus-observed entry contradiction", () => {
|
|
const native = projectAnalysisError(
|
|
new ArtifactOperationError(
|
|
"inspect_artifact",
|
|
"integrity",
|
|
undefined,
|
|
"hdiutil verify failed: invalid checksum",
|
|
),
|
|
);
|
|
expect(native.category).toBe("integrity_mismatch");
|
|
expect(native.details).toMatchObject({
|
|
reason: "integrity",
|
|
detail: "hdiutil verify failed: invalid checksum",
|
|
});
|
|
expect(native.message).not.toContain("record-and-continue");
|
|
expect(native.remediation.action).not.toContain("record-and-continue");
|
|
});
|
|
|
|
it("preserves ordinary configuration recovery and projects a producer-owned session repair", () => {
|
|
const settings = [{ setting: "REA_EXAMPLE", constraint: "must be positive" }];
|
|
const original = projectAnalysisError(
|
|
new ConfigurationError("Invalid setting", { settings }),
|
|
);
|
|
const repairing = projectAnalysisError(
|
|
new ConfigurationError("Invalid setting", {
|
|
settings,
|
|
remediationAction: "Repair the running session, then retry.",
|
|
}),
|
|
);
|
|
expect(original.remediation.action).toBe(
|
|
"Correct REA_EXAMPLE in the environment that starts REA (your shell or the MCP client's registration), then rerun.",
|
|
);
|
|
expect(repairing).toEqual({
|
|
...original,
|
|
remediation: { action: "Repair the running session, then retry." },
|
|
});
|
|
expect(repairing.code).toBe("configuration_invalid");
|
|
});
|