Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
refactor(cleanup): share failure composition and retain native UI owners
morluto2a0b58e4403d
diff --git a/src/application/DirectAnalysisCleanup.ts b/src/application/DirectAnalysisCleanup.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 90056c3b2..172adda8e 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -99,6 +99,7 @@ import type { BrowserScenarioPartialObservation } from "./browserScenarioCaptureimport 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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();}};