Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

refactor(cleanup): share failure composition and retain native UI owners

morluto2a0b58e4403d
diff --git a/src/application/DirectAnalysisCleanup.ts b/src/application/DirectAnalysisCleanup.ts
index 3f073f7b5..0a49f0d5f 100644
--- a/src/application/DirectAnalysisCleanup.ts
+++ b/src/application/DirectAnalysisCleanup.ts
@@ -6,7 +6,7 @@ import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { err, type Result } from "../domain/result.js";
import type { AnalysisExecution } from "./AnalysisProvider.js";
import type { BinarySession } from "./binary/BinarySession.js";
-import { analysisErrorWithCleanupFailure } from "./binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
/** Await one-shot cleanup and retain either the outcome or both failures. */
export const withSessionCleanup = async <Value>(
diff --git a/src/application/binary/AnalysisClientCleanup.test.ts b/src/application/binary/AnalysisClientCleanup.test.ts
index f4ada3822..e3dae7646 100644
--- a/src/application/binary/AnalysisClientCleanup.test.ts
+++ b/src/application/binary/AnalysisClientCleanup.test.ts
@@ -5,10 +5,8 @@ import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import { err } from "../../domain/result.js";
import type { AnalysisClient } from "../AnalysisProvider.js";
-import {
- analysisErrorWithCleanupFailure,
- closeAnalysisClient,
-} from "./AnalysisClientCleanup.js";
+import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
const clientClosingWith = (cause: unknown): AnalysisClient => ({
execute: () => Promise.resolve(err(new ProviderCleanupError("x", [], {}))),
diff --git a/src/application/binary/AnalysisClientCleanup.ts b/src/application/binary/AnalysisClientCleanup.ts
index a693d2d8b..db283cc25 100644
--- a/src/application/binary/AnalysisClientCleanup.ts
+++ b/src/application/binary/AnalysisClientCleanup.ts
@@ -1,6 +1,4 @@
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
-import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
-import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { err, type Result } from "../../domain/result.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { AnalysisClient, ExecutionOptions } from "../AnalysisProvider.js";
@@ -29,34 +27,3 @@ export const closeAnalysisClient = async (
);
}
};
-
-/** Preserve the original lifecycle failure alongside incomplete cleanup. */
-export const analysisErrorWithCleanupFailure = (
- primary: AnalysisError,
- cleanup: AnalysisError,
- operation = "close_binary",
-): AnalysisError => {
- const projected = projectAnalysisError(cleanup);
- return new ProviderAdapterError(
- cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea",
- operation,
- {
- cause: primary,
- userMessage: projectAnalysisError(primary).message,
- ...(primary.capturedOutput === undefined
- ? {}
- : { capturedOutput: primary.capturedOutput }),
- ...(primary.partialObservation === undefined
- ? {}
- : { partialObservation: primary.partialObservation }),
- cleanup: {
- reason: projected.message,
- resources: cleanup.cleanupResources,
- },
- diagnostics: {
- primary_error: projectAnalysisError(primary),
- cleanup_error: projected,
- },
- },
- );
-};
diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts
index b9ff6a23c..bcf4da184 100644
--- a/src/application/binary/BinarySession.ts
+++ b/src/application/binary/BinarySession.ts
@@ -44,10 +44,8 @@ import {
commitExecutionProfile,
prepareSessionExecution,
} from "./BinarySessionExecution.js";
-import {
- analysisErrorWithCleanupFailure,
- closeAnalysisClient,
-} from "./AnalysisClientCleanup.js";
+import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";
const OFFICIAL_OPERATIONS: ReadonlySet<string> = new Set(
OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name),
);
diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.ts
index 90056c3b2..172adda8e 100644
--- a/src/domain/analysisErrorBase.ts
+++ b/src/domain/analysisErrorBase.ts
@@ -99,6 +99,7 @@ import type { BrowserScenarioPartialObservation } from "./browserScenarioCapture
import type { Evidence } from "./evidence.js";
import type { AndroidPartialObservation } from "./android/androidPartialObservation.js";
import type { FirmwarePartialObservation } from "./firmware/firmwareAnalysis.js";
+import type { NativeUiObservationResult } from "./native/nativeUiObservation.js";
/** Provider-neutral evidence collected before a typed analysis failure. */
export type AnalysisPartialObservation =
@@ -111,4 +112,5 @@ export type AnalysisPartialObservation =
| ArtifactInventoryPartialObservation
| Evidence
| AndroidPartialObservation
- | FirmwarePartialObservation;
+ | FirmwarePartialObservation
+ | NativeUiObservationResult;
diff --git a/src/domain/analysisErrorCleanup.ts b/src/domain/analysisErrorCleanup.ts
new file mode 100644
index 000000000..df1f95b75
--- /dev/null
+++ b/src/domain/analysisErrorCleanup.ts
@@ -0,0 +1,39 @@
+import { ProviderAdapterError } from "./providerAdapterError.js";
+import { projectAnalysisError } from "./analysisErrorProjection.js";
+import type { AnalysisError } from "./analysisErrorBase.js";
+
+/** Preserve the original lifecycle failure alongside incomplete cleanup. */
+export const analysisErrorWithCleanupFailure = (
+ primary: AnalysisError,
+ cleanup: AnalysisError,
+ operation = "close_binary",
+): AnalysisError => {
+ const projected = projectAnalysisError(cleanup);
+ return new ProviderAdapterError(
+ cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea",
+ operation,
+ {
+ cause: primary,
+ userMessage: projectAnalysisError(primary).message,
+ ...(primary.capturedOutput === undefined
+ ? {}
+ : { capturedOutput: primary.capturedOutput }),
+ ...(primary.partialObservation === undefined
+ ? {}
+ : { partialObservation: primary.partialObservation }),
+ cleanup: {
+ reason: projected.message,
+ resources: [
+ ...new Set([
+ ...primary.cleanupResources,
+ ...cleanup.cleanupResources,
+ ]),
+ ],
+ },
+ diagnostics: {
+ primary_error: projectAnalysisError(primary),
+ cleanup_error: projected,
+ },
+ },
+ );
+};
diff --git a/src/domain/native/nativeUiObservation.ts b/src/domain/native/nativeUiObservation.ts
index a9378ad7b..392d4d8db 100644
--- a/src/domain/native/nativeUiObservation.ts
+++ b/src/domain/native/nativeUiObservation.ts
@@ -156,3 +156,5 @@ export const nativeUiResultSchema = z.strictObject({
restore: z.literal("leave-as-is"),
limitations: z.array(z.string()),
});
+
+export type NativeUiObservationResult = z.infer<typeof nativeUiResultSchema>;
diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts
index bd4015ac1..4ee4c8b82 100644
--- a/src/ghidra/GhidraProviderClient.ts
+++ b/src/ghidra/GhidraProviderClient.ts
@@ -1,4 +1,4 @@
-import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { fileURLToPath } from "node:url";
import {
diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts
index 345076969..14c5d6965 100644
--- a/src/hopper/HopperClient.ts
+++ b/src/hopper/HopperClient.ts
@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import writeFileAtomic from "write-file-atomic";
-import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
import {
HopperCancelledError,
diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.ts
index d63db2506..d44409984 100644
--- a/src/native/NativeMacOSProvider.ts
+++ b/src/native/NativeMacOSProvider.ts
@@ -36,10 +36,13 @@ import {
AnalysisResourceConstraintError,
AnalysisTimeoutError,
} from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
+import type { NativeUiObservationResult } from "../domain/native/nativeUiObservation.js";
import {
omittedPrototypeKeysLimitation,
parseXmlPropertyList,
@@ -77,6 +80,11 @@ import {
architectureLocations,
inspectNativeMacho,
} from "./NativeMachoInspection.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import {
+ createNativeUiHelperRuntime,
+ type NativeUiHelperRuntime,
+} from "./NativeUiHelperRuntime.js";
/** Read-only semantic provider composed from Xcode command-line utilities. */
export class NativeMacOSProvider implements AnalysisProvider {
@@ -117,6 +125,10 @@ export class NativeMacOSProvider implements AnalysisProvider {
}
class NativeMacOSClient implements AnalysisClient {
+ readonly #pendingNativeUiRuntimes = new Set<NativeUiHelperRuntime>();
+ #nativeUiTail: Promise<void> = Promise.resolve();
+ #closed = false;
+
constructor(
private readonly target: BinaryTarget,
private readonly runner: NativeCommandRunner,
@@ -129,6 +141,14 @@ class NativeMacOSClient implements AnalysisClient {
parameters: Readonly<Record<string, JsonValue>>,
options?: { readonly signal?: AbortSignal },
) {
+ if (this.#closed)
+ return err(
+ new AnalysisCapabilityUnavailableError(
+ IDENTITY.id,
+ operation,
+ "Native provider client is closed",
+ ),
+ );
if (options?.signal?.aborted === true)
return err(new AnalysisCancelledError(operation));
if (operation === "health")
@@ -212,17 +232,7 @@ class NativeMacOSClient implements AnalysisClient {
operation === "observe_native_ui" ||
operation === "capture_native_ui_scenario"
) {
- const result = await observeNativeUi(this.target, operation, parameters, {
- environment: this.environment,
- signal: options?.signal,
- });
- return result.ok
- ? ok(
- createAnalysisExecution(result.value, IDENTITY, {
- limitations: result.value.limitations,
- }),
- )
- : result;
+ return this.#observeNativeUi(operation, parameters, options?.signal);
}
try {
const observation = await this.#dispatch(
@@ -247,8 +257,137 @@ class NativeMacOSClient implements AnalysisClient {
}
}
- close(): Promise<Result<null, AnalysisError>> {
- return this.tracer.close();
+ async close(): Promise<Result<null, AnalysisError>> {
+ this.#closed = true;
+ const uiCleanupFailures = await this.#serializeNativeUi(() =>
+ this.#retryNativeUiCleanup(),
+ );
+ const tracer = await this.tracer.close();
+ if (uiCleanupFailures.length === 0) return tracer;
+ const uiCleanup = this.#nativeUiCleanupFailure(
+ uiCleanupFailures,
+ "close_binary",
+ );
+ return tracer.ok
+ ? err(uiCleanup)
+ : err(analysisErrorWithCleanupFailure(tracer.error, uiCleanup));
+ }
+
+ #observeNativeUi(
+ operation: "observe_native_ui" | "capture_native_ui_scenario",
+ parameters: Readonly<Record<string, JsonValue>>,
+ signal?: AbortSignal,
+ ) {
+ return this.#serializeNativeUi(async () => {
+ if (this.#closed)
+ return err(
+ new AnalysisCapabilityUnavailableError(
+ IDENTITY.id,
+ operation,
+ "Native provider client is closed",
+ ),
+ );
+ const earlierCleanupFailures = await this.#retryNativeUiCleanup();
+ if (earlierCleanupFailures.length > 0)
+ return err(
+ this.#nativeUiCleanupFailure(earlierCleanupFailures, operation),
+ );
+ const runtime = createNativeUiHelperRuntime(this.environment);
+ this.#pendingNativeUiRuntimes.add(runtime);
+ let result: Awaited<ReturnType<typeof observeNativeUi>>;
+ try {
+ result = await observeNativeUi(this.target, operation, parameters, {
+ environment: this.environment,
+ signal,
+ runtime,
+ });
+ } catch (cause: unknown) {
+ result = err(
+ cause instanceof AnalysisError
+ ? cause
+ : new ProviderAdapterError(IDENTITY.id, operation, { cause }),
+ );
+ }
+ try {
+ await runtime.close();
+ this.#pendingNativeUiRuntimes.delete(runtime);
+ } catch (cause: unknown) {
+ const cleanup = this.#nativeUiCleanupFailure(
+ [{ runtime, cause }],
+ operation,
+ result.ok ? result.value : undefined,
+ );
+ return err(
+ result.ok
+ ? cleanup
+ : analysisErrorWithCleanupFailure(result.error, cleanup, operation),
+ );
+ }
+ return result.ok
+ ? ok(
+ createAnalysisExecution(result.value, IDENTITY, {
+ limitations: result.value.limitations,
+ }),
+ )
+ : result;
+ });
+ }
+
+ #serializeNativeUi<Value>(operation: () => Promise<Value>): Promise<Value> {
+ const call = this.#nativeUiTail.then(operation, operation);
+ this.#nativeUiTail = call.then(
+ () => undefined,
+ () => undefined,
+ );
+ return call;
+ }
+
+ async #retryNativeUiCleanup(): Promise<
+ Array<{ readonly runtime: NativeUiHelperRuntime; readonly cause: unknown }>
+ > {
+ const failures: Array<{
+ readonly runtime: NativeUiHelperRuntime;
+ readonly cause: unknown;
+ }> = [];
+ for (const runtime of this.#pendingNativeUiRuntimes) {
+ try {
+ await runtime.close();
+ this.#pendingNativeUiRuntimes.delete(runtime);
+ } catch (cause: unknown) {
+ failures.push({ runtime, cause });
+ }
+ }
+ return failures;
+ }
+
+ #nativeUiCleanupFailure(
+ failures: readonly {
+ readonly runtime: NativeUiHelperRuntime;
+ readonly cause: unknown;
+ }[],
+ operation: string,
+ partialObservation?: NativeUiObservationResult,
+ ): ProviderCleanupError {
+ const resources = failures.flatMap(({ runtime }) => runtime.resources());
+ return new ProviderCleanupError(
+ IDENTITY.id,
+ resources.length === 0 ? ["native-ui-runtime"] : resources,
+ {
+ reason: "Native UI runtime cleanup remains incomplete",
+ failures: failures.map(({ runtime, cause }) => ({
+ resources: [...runtime.resources()],
+ reason: cause instanceof Error ? cause.message : String(cause),
+ })),
+ },
+ {
+ operation,
+ cause: new AggregateError(
+ failures.map(({ cause }) => cause),
+ "Native UI runtime cleanup failed",
+ ),
+ ...(partialObservation === undefined ? {} : { partialObservation }),
+ },
+ );
}
#dispatch(
diff --git a/src/native/NativeUiHelperRuntime.ts b/src/native/NativeUiHelperRuntime.ts
index 3107a4b33..dfeae245d 100644
--- a/src/native/NativeUiHelperRuntime.ts
+++ b/src/native/NativeUiHelperRuntime.ts
@@ -9,10 +9,16 @@ import { safeParseJson } from "../domain/safeJson.js";
import type { NativeUiHelper } from "./NativeUiObservation.js";
import { NATIVE_UI_HELPER_MAX_BUFFER } from "./NativeUiOutputBudget.js";
+export interface NativeUiHelperRuntime {
+ readonly invoke: NativeUiHelper;
+ close(): Promise<void>;
+ resources(): readonly string[];
+}
+
/** Lazily compile one owned helper per observation/scenario and remove its compiler cache. */
export const createNativeUiHelperRuntime = (
environment: Readonly<NodeJS.ProcessEnv>,
-) => {
+): NativeUiHelperRuntime => {
const selectedEnvironment = snapshotEnvironment(environment);
let root: string | undefined;
let executable: string | undefined;
@@ -62,6 +68,7 @@ export const createNativeUiHelperRuntime = (
{
timeout: 30_000,
maxBuffer: NATIVE_UI_HELPER_MAX_BUFFER,
+ stopSignal: "SIGTERM",
env: selectedEnvironment,
...(signal === undefined ? {} : { signal }),
},
@@ -76,7 +83,12 @@ export const createNativeUiHelperRuntime = (
return {
invoke,
close: async () => {
- if (root !== undefined) await rm(root, { recursive: true, force: true });
+ if (root !== undefined) {
+ await rm(root, { recursive: true, force: true });
+ root = undefined;
+ executable = undefined;
+ }
},
+ resources: () => (root === undefined ? [] : [root]),
};
};
diff --git a/src/native/NativeUiObservation.ts b/src/native/NativeUiObservation.ts
index 73d301042..9dc337189 100644
--- a/src/native/NativeUiObservation.ts
+++ b/src/native/NativeUiObservation.ts
@@ -15,7 +15,10 @@ import {
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { type AnalysisError } from "../domain/analysisErrorBase.js";
import { err, ok, type Result } from "../domain/result.js";
-import { createNativeUiHelperRuntime } from "./NativeUiHelperRuntime.js";
+import {
+ createNativeUiHelperRuntime,
+ type NativeUiHelperRuntime,
+} from "./NativeUiHelperRuntime.js";
import {
NATIVE_UI_OUTPUT_BUDGET_BYTES,
NATIVE_UI_OUTPUT_WEIGHT,
@@ -47,16 +50,18 @@ export const observeNativeUi = async (
environment: Readonly<NodeJS.ProcessEnv>;
signal?: AbortSignal | undefined;
invoke?: NativeUiHelper;
+ runtime?: NativeUiHelperRuntime;
},
): Promise<Result<z.infer<typeof nativeUiResultSchema>, AnalysisError>> => {
- const runtime = createNativeUiHelperRuntime(options.environment);
+ const runtime =
+ options.runtime ?? createNativeUiHelperRuntime(options.environment);
try {
return await observeWithHelper(target, operation, parameters, {
...options,
invoke: options.invoke ?? runtime.invoke,
});
} finally {
- await runtime.close();
+ if (options.runtime === undefined) await runtime.close();
}
};