rea-agents 6.3.0 → 6.5.0

package/dist/domain/adb/adbDeviceAnalysis.js

@@ -0,0 +1,605 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { IDENTIFIER_PATTERN } from "../stringPatterns.js";
+/**
+ * Device serials as adb prints them: emulator-5554, USB identifiers, and
+ * host:port transports. The pattern keeps arguments free of whitespace and
+ * quotes; argv is positional in the provider, so this is admission hygiene
+ * rather than injection defense.
+ */
+const deviceSerialSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[^\x00\s"']+$/u, "Device serial cannot contain whitespace or quotes");
+/**
+ * Android package names as Package Manager reports them. System entries can
+ * be a single segment (`android`), so at least one identifier is required.
+ */
+const packageNameSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/u, "Package name must be dot-separated Java identifiers");
+/** Text states emitted by adb's ConnectionState formatter. */
+export const ADB_DEVICE_STATES = [
+    "no permissions",
+    "unauthorized",
+    "authorizing",
+    "offline",
+    "recovery",
+    "sideload",
+    "connecting",
+    "bootloader",
+    "device",
+    "unknown",
+    "host",
+    "rescue",
+    "detached",
+];
+export const adbDeviceStateSchema = z.enum(ADB_DEVICE_STATES);
+const keyStringSchema = z.string().min(1).max(256);
+const keyPattern = /^[A-Za-z0-9._\x2d]+$/u;
+/**
+ * Caller intent for ADB-backed device inspection and acquisition.
+ *
+ * REA never installs platform tools, starts an emulator, or manages devices;
+ * every operation addresses devices the caller already connected, through the
+ * adb binary the caller selected.
+ */
+export const adbInputSchemas = {
+    inspect_adb_client: z.strictObject({}),
+    list_adb_devices: z.strictObject({}),
+    inspect_adb_device: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+    }),
+    list_adb_packages: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        scope: z
+            .enum(["all", "third_party", "system"])
+            .default("all")
+            .describe("Package scope: all packages, third-party only (-3), or system only (-s)"),
+    }),
+    pull_adb_package: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        package: packageNameSchema.describe("Installed package name whose APK set is pulled"),
+        output_directory: localPathStringSchema.describe("Local directory for the pulled APK set; REA creates a package-named subdirectory inside it"),
+    }),
+    read_adb_logcat: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(10_000)
+            .default(500)
+            .describe("Number of most recent lines to read (logcat -d -t)"),
+        buffer: z
+            .enum(["main", "system", "radio", "events", "crash"])
+            .default("main")
+            .describe("Log buffer to read (logcat -b)"),
+        pid: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Restrict to one process id (logcat --pid)"),
+    }),
+    inspect_adb_package: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        package: packageNameSchema.describe("Installed package to inspect"),
+    }),
+    pull_adb_file: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        device_path: z
+            .string()
+            .min(1)
+            .regex(/^\/[^\x00]*$/u, "Device path must be absolute")
+            .describe("Absolute device filesystem path to pull"),
+        output_directory: localPathStringSchema.describe("Local directory for the pulled file; must not already contain the file"),
+    }),
+    push_adb_file: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        local_path: localPathStringSchema.describe("Existing local regular file to push"),
+        device_path: z
+            .string()
+            .min(1)
+            .regex(/^\/[^\x00]*$/u, "Device path must be absolute")
+            .describe("Absolute destination path on the device"),
+        overwrite: z
+            .boolean()
+            .default(false)
+            .describe("Allow replacing an existing device file; refused by default"),
+    }),
+    capture_adb_screen: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        output_directory: localPathStringSchema.describe("Local directory for the captured PNG; must not already contain it"),
+    }),
+    list_adb_processes: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+    }),
+    list_adb_directory: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        device_path: z
+            .string()
+            .min(1)
+            .regex(/^\/[^\x00]*$/u, "Device path must be absolute")
+            .describe("Absolute device directory path to list, including hidden children"),
+    }),
+    list_adb_features: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+    }),
+    list_adb_services: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+    }),
+    inspect_adb_display: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+    }),
+    inspect_adb_window: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+    }),
+    read_adb_setting: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        namespace: z
+            .enum(["system", "secure", "global"])
+            .describe("Settings namespace to read"),
+        key: keyStringSchema
+            .regex(keyPattern, "Setting keys are restricted to identifiers")
+            .describe("Setting key to read"),
+    }),
+    collect_adb_bugreport: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        output_directory: localPathStringSchema.describe("Local directory for the bugreport archive; REA writes exactly one new zip into it"),
+    }),
+    resolve_adb_packages: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        query: z
+            .string()
+            .min(2)
+            .max(256)
+            .describe("Case-insensitive substring matched against installed package names (e.g. whatsapp)"),
+    }),
+    install_adb_package: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        apk_path: localPathStringSchema.describe("Existing local APK file to install"),
+        replace: z
+            .boolean()
+            .default(false)
+            .describe("Request replacement mode and keep existing app data if present (adb install -r); does not establish whether the app was already installed"),
+    }),
+    uninstall_adb_package: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        package: packageNameSchema.describe("Installed package to uninstall"),
+    }),
+    start_adb_app: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        package: packageNameSchema.describe("Installed package whose launcher activity is started"),
+    }),
+    start_adb_activity: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        action: z
+            .string()
+            .min(1)
+            .max(256)
+            .regex(IDENTIFIER_PATTERN, "Intent action must be a dotted identifier such as android.intent.action.VIEW")
+            .describe("Intent action to start"),
+        data_uri: z
+            .string()
+            .min(1)
+            .max(2048)
+            .regex(/^[^\x00\s]+$/u, "Data URI cannot contain whitespace or NUL")
+            .optional()
+            .describe("Intent data URI (-d)"),
+        component: z
+            .string()
+            .min(1)
+            .max(512)
+            .regex(/^[A-Za-z0-9._\x2d]+(\/[A-Za-z0-9._\x2d]*)?$/u, "Component must be package/activity form")
+            .optional()
+            .describe("Explicit component to start (-n)"),
+        extras: z
+            .array(z.strictObject({
+            key: keyStringSchema
+                .regex(keyPattern, "Extra keys are identifiers")
+                .describe("Extra key"),
+            type: z
+                .enum(["string", "boolean", "int", "long", "float"])
+                .describe("Extra value type"),
+            value: z
+                .string()
+                .min(1)
+                .max(2048)
+                .regex(/^[^\x00]*$/u, "Extra values cannot contain NUL")
+                .describe("Extra value as text, parsed per type"),
+        }))
+            .max(16)
+            .default([])
+            .describe("Typed intent extras (--es/--ez/--ei/--el/--ef)"),
+    }),
+    stop_adb_app: z.strictObject({
+        serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
+        package: packageNameSchema.describe("Package whose processes are force-stopped"),
+    }),
+};
+/** Validate operation and input together so their types remain correlated. */
+export const adbRequestSchema = z.discriminatedUnion("operation", [
+    z.strictObject({
+        operation: z.literal("inspect_adb_client"),
+        input: adbInputSchemas.inspect_adb_client,
+    }),
+    z.strictObject({
+        operation: z.literal("list_adb_devices"),
+        input: adbInputSchemas.list_adb_devices,
+    }),
+    z.strictObject({
+        operation: z.literal("inspect_adb_device"),
+        input: adbInputSchemas.inspect_adb_device,
+    }),
+    z.strictObject({
+        operation: z.literal("list_adb_packages"),
+        input: adbInputSchemas.list_adb_packages,
+    }),
+    z.strictObject({
+        operation: z.literal("pull_adb_package"),
+        input: adbInputSchemas.pull_adb_package,
+    }),
+    z.strictObject({
+        operation: z.literal("read_adb_logcat"),
+        input: adbInputSchemas.read_adb_logcat,
+    }),
+    z.strictObject({
+        operation: z.literal("inspect_adb_package"),
+        input: adbInputSchemas.inspect_adb_package,
+    }),
+    z.strictObject({
+        operation: z.literal("pull_adb_file"),
+        input: adbInputSchemas.pull_adb_file,
+    }),
+    z.strictObject({
+        operation: z.literal("push_adb_file"),
+        input: adbInputSchemas.push_adb_file,
+    }),
+    z.strictObject({
+        operation: z.literal("capture_adb_screen"),
+        input: adbInputSchemas.capture_adb_screen,
+    }),
+    z.strictObject({
+        operation: z.literal("list_adb_processes"),
+        input: adbInputSchemas.list_adb_processes,
+    }),
+    z.strictObject({
+        operation: z.literal("list_adb_directory"),
+        input: adbInputSchemas.list_adb_directory,
+    }),
+    z.strictObject({
+        operation: z.literal("list_adb_features"),
+        input: adbInputSchemas.list_adb_features,
+    }),
+    z.strictObject({
+        operation: z.literal("list_adb_services"),
+        input: adbInputSchemas.list_adb_services,
+    }),
+    z.strictObject({
+        operation: z.literal("inspect_adb_display"),
+        input: adbInputSchemas.inspect_adb_display,
+    }),
+    z.strictObject({
+        operation: z.literal("inspect_adb_window"),
+        input: adbInputSchemas.inspect_adb_window,
+    }),
+    z.strictObject({
+        operation: z.literal("read_adb_setting"),
+        input: adbInputSchemas.read_adb_setting,
+    }),
+    z.strictObject({
+        operation: z.literal("collect_adb_bugreport"),
+        input: adbInputSchemas.collect_adb_bugreport,
+    }),
+    z.strictObject({
+        operation: z.literal("resolve_adb_packages"),
+        input: adbInputSchemas.resolve_adb_packages,
+    }),
+    z.strictObject({
+        operation: z.literal("install_adb_package"),
+        input: adbInputSchemas.install_adb_package,
+    }),
+    z.strictObject({
+        operation: z.literal("uninstall_adb_package"),
+        input: adbInputSchemas.uninstall_adb_package,
+    }),
+    z.strictObject({
+        operation: z.literal("start_adb_app"),
+        input: adbInputSchemas.start_adb_app,
+    }),
+    z.strictObject({
+        operation: z.literal("start_adb_activity"),
+        input: adbInputSchemas.start_adb_activity,
+    }),
+    z.strictObject({
+        operation: z.literal("stop_adb_app"),
+        input: adbInputSchemas.stop_adb_app,
+    }),
+]);
+const client = z.strictObject({
+    binary_path: z.string().min(1),
+    path_source: z.enum(["environment", "path"]),
+    version: z.string().min(1).nullable(),
+    installed_path: z.string().min(1).nullable(),
+});
+const device = z.strictObject({
+    serial: z.string().min(1),
+    state: adbDeviceStateSchema,
+    transport: z.enum(["usb", "tcp", "unknown"]),
+    product: z.string().nullable(),
+    model: z.string().nullable(),
+    device: z.string().nullable(),
+    transport_id: z.number().int().positive().nullable(),
+    /**
+     * Inferred device kind with its evidence basis. The serial prefix and the
+     * `device:` metadata line are observations; the kind itself is derived.
+     */
+    kind: z.enum(["emulator", "physical", "unknown"]),
+    kind_basis: z.enum(["emulator_serial_prefix", "usb_transport", "none"]),
+});
+const pulledArtifact = z.strictObject({
+    device_path: z.string().min(1),
+    file_name: z.string().min(1),
+    local_path: z.string().min(1),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    role: z.enum(["base", "split", "unknown"]),
+    role_basis: z.literal("file_name"),
+});
+const pullFailure = z.strictObject({
+    device_path: z.string().min(1).nullable(),
+    stage: z.enum(["resolve_paths", "pull", "digest"]),
+    message: z.string().min(1),
+});
+/** Portable ADB observations with explicit identity and coverage limitations. */
+export const adbResultSchemas = {
+    inspect_adb_client: z.strictObject({
+        client,
+        /**
+         * `adb version` never contacts the adb server; this tool starts nothing.
+         * Recorded explicitly so the session keeps the distinction observable.
+         */
+        contacted_adb_server: z.literal(false),
+    }),
+    list_adb_devices: z.strictObject({
+        client,
+        devices: z.array(device),
+        /**
+         * Starting the local adb server is an adb client behavior on first use;
+         * REA observes whichever server state the caller's environment has.
+         */
+        may_have_started_adb_server: z.boolean(),
+    }),
+    inspect_adb_device: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        properties: z.array(z.strictObject({ name: z.string().min(1), value: z.string().min(1) })),
+        property_count: z.number().int().nonnegative(),
+        emulator_observed: z.boolean().nullable(),
+    }),
+    list_adb_packages: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        scope: z.enum(["all", "third_party", "system"]),
+        packages: z.array(z.strictObject({
+            package_name: packageNameSchema,
+            /** Device filesystem path; not a host-local path. */
+            base_apk_device_path: z.string().min(1),
+        })),
+        unparsed_lines: z.array(z.string().min(1)),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    pull_adb_package: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        package_name: packageNameSchema,
+        output_directory: z.string().min(1),
+        artifacts: z.array(pulledArtifact),
+        failures: z.array(pullFailure),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    read_adb_logcat: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        count: z.number().int().positive(),
+        buffer: z.enum(["main", "system", "radio", "events", "crash"]),
+        pid: z.number().int().positive().nullable(),
+        lines: z.array(z.string()),
+        total_bytes: z.number().int().nonnegative(),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    inspect_adb_package: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        package_name: packageNameSchema,
+        version_name: z.string().nullable(),
+        version_code: z.number().int().nullable(),
+        first_install_time: z.string().nullable(),
+        last_update_time: z.string().nullable(),
+        installer_package_name: z.string().nullable(),
+        user_id: z.number().int().nullable(),
+        pkg_flags: z.string().nullable(),
+        requested_permissions_count: z.number().int().nonnegative().nullable(),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    pull_adb_file: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        device_path: z.string().min(1),
+        local_path: z.string().min(1),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
+    push_adb_file: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        local_path: z.string().min(1),
+        device_path: z.string().min(1),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        device_sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .nullable(),
+        overwritten: z.boolean(),
+        device_digest_source: z.enum(["device_sha256sum", "unavailable"]),
+    }),
+    capture_adb_screen: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        local_path: z.string().min(1),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        width: z.number().int().positive().nullable(),
+        height: z.number().int().positive().nullable(),
+    }),
+    list_adb_processes: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        columns: z.string().nullable(),
+        processes: z.array(z.strictObject({
+            user: z.string(),
+            pid: z.number().int().nonnegative(),
+            ppid: z.number().int().nullable(),
+            rss: z.number().int().nullable(),
+            state: z.string().nullable(),
+            name: z.string(),
+        })),
+        unparsed_lines: z.array(z.string().min(1)),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    list_adb_directory: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        device_path: z.string().min(1),
+        entries: z.array(z.strictObject({
+            name: z.string().min(1),
+            kind: z.enum(["directory", "file", "symlink", "other"]),
+            permissions: z.string().nullable(),
+            owner: z.string().nullable(),
+            group: z.string().nullable(),
+            bytes: z.number().int().nullable(),
+            date: z.string().nullable(),
+            link_target: z.string().nullable(),
+        })),
+        unparsed_lines: z.array(z.string().min(1)),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    list_adb_features: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        features: z.array(z.strictObject({
+            name: z.string().min(1),
+            version: z.number().int().nullable(),
+        })),
+        unparsed_lines: z.array(z.string().min(1)),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    list_adb_services: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        services: z.array(z.strictObject({
+            name: z.string().min(1),
+            interface: z.string().nullable(),
+        })),
+        unparsed_lines: z.array(z.string().min(1)),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    inspect_adb_display: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        physical_size: z.strictObject({
+            width: z.number().int().positive(),
+            height: z.number().int().positive(),
+        }),
+        override_size: z
+            .strictObject({
+            width: z.number().int().positive(),
+            height: z.number().int().positive(),
+        })
+            .nullable(),
+        physical_density: z.number().int().positive().nullable(),
+        override_density: z.number().int().positive().nullable(),
+    }),
+    inspect_adb_window: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        focused_window: z.string().nullable(),
+        focused_app: z.string().nullable(),
+        observed_lines: z.array(z.string().min(1)),
+    }),
+    read_adb_setting: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        namespace: z.enum(["system", "secure", "global"]),
+        key: z.string().min(1),
+        value: z.string().nullable(),
+        device_reported_null: z.boolean(),
+    }),
+    collect_adb_bugreport: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        local_path: z.string().min(1),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        adb_reported_path: z.string().nullable(),
+    }),
+    resolve_adb_packages: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        query: z.string().min(1),
+        matches: z.array(z.strictObject({
+            package_name: packageNameSchema,
+            base_apk_device_path: z.string().min(1),
+        })),
+        exact_match: z.boolean(),
+        coverage: z.enum(["complete", "partial"]),
+    }),
+    install_adb_package: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        apk_path: z.string().min(1),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+        replace_requested: z.boolean(),
+        replaced: z.boolean().nullable(),
+    }),
+    uninstall_adb_package: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        package_name: packageNameSchema,
+    }),
+    start_adb_app: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        package_name: packageNameSchema,
+        component: z.string().min(1),
+        started_activity: z.string().nullable(),
+        reported_activity: z.string().nullable().optional(),
+        reported_status: z.string().nullable().optional(),
+    }),
+    start_adb_activity: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        action: z.string().min(1),
+        data_uri: z.string().nullable(),
+        component: z.string().nullable(),
+        extras: z.array(z.strictObject({
+            key: z.string().min(1),
+            type: z.enum(["string", "boolean", "int", "long", "float"]),
+            value: z.string(),
+        })),
+        started_activity: z.string().nullable(),
+        reported_activity: z.string().nullable().optional(),
+        reported_status: z.string().nullable().optional(),
+    }),
+    stop_adb_app: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        package_name: packageNameSchema,
+    }),
+};

package/dist/domain/analysisErrorBase.js

@@ -30,12 +30,17 @@ const ANALYSIS_ERROR_TAGS = [
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
+    diagnostics;
     capturedOutput;
     cleanup;
     cleanupIncomplete;
     cleanupResources;
     constructor(message, options) {
         super(message, options);
+        this.diagnostics =
+            options?.diagnostics === undefined
+                ? undefined
+                : structuredClone(options.diagnostics);
         this.capturedOutput =
             options?.capturedOutput === undefined
                 ? undefined
@@ -50,6 +55,21 @@ export class AnalysisError extends Error {
     executionFailure = undefined;
     partialObservation;
     cleanupReport = undefined;
+    /** Retain a later lifecycle failure without replacing the original typed error. */
+    retainSecondaryFailure(failure, diagnostics) {
+        // Secondary resources remain owned by their cleanup lifecycle; preserve
+        // the primary error's live cleanup status and original output.
+        Object.assign(this, {
+            diagnostics: structuredClone({ ...this.diagnostics, ...diagnostics }),
+            cause: new AggregateError(this.cause === undefined ? [failure] : [this.cause, failure], "Analysis failed and a later lifecycle operation also failed.", { cause: this.cause }),
+        });
+        return this;
+    }
+    /** Clear live cleanup status only after its owning resource confirms retry success. */
+    resolveCleanup() {
+        this.cleanupIncomplete = false;
+        return this;
+    }
     /** Retain a completed observation when a later step fails. */
     retainPartialObservation(observation) {
         this.partialObservation ??= observation;

package/dist/domain/analysisErrorCleanup.js

@@ -0,0 +1,29 @@
+import { ProviderAdapterError } from "./providerAdapterError.js";
+import { projectAnalysisError } from "./analysisErrorProjection.js";
+/** Preserve the original lifecycle failure alongside incomplete cleanup. */
+export const analysisErrorWithCleanupFailure = (primary, cleanup, operation = "close_binary") => {
+    const projected = projectAnalysisError(cleanup);
+    return new ProviderAdapterError(cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea", operation, {
+        cause: new AggregateError([primary, cleanup], "Analysis failed and cleanup remains incomplete.", { 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,
+        },
+    });
+};