rea-agents 6.3.0 → 6.4.0

package/dist/domain/adb/adbDeviceAnalysis.js

@@ -0,0 +1,583 @@
+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");
+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 (ls -la)"),
+    }),
+    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("Replace an existing installation and keep its data (adb install -r)"),
+    }),
+    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: z.string().min(1),
+    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),
+        replaced: z.boolean(),
+    }),
+    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(),
+    }),
+    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(),
+    }),
+    stop_adb_app: z.strictObject({
+        client,
+        serial: z.string().min(1),
+        package_name: packageNameSchema,
+    }),
+};

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: 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,
+        },
+    });
+};

package/dist/domain/analysisErrorPresentation.js

@@ -18,7 +18,7 @@ export const analysisErrorRemediationAction = (error) => {
     if (error instanceof AnalysisResourceConstraintError)
         return (error.remediationAction ??
             (error.resource === "transport"
-                ? "Export retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. Tools that accept retained-evidence references can inspect compatible records. The connection remains usable."
+                ? "Discover retained records with get_evidence_bundle and detail: summary, then inspect compatible records through inspect_analysis_view using an exact Evidence reference. Export complete retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. The connection remains usable."
                 : error.resource === "cpu"
                     ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
                     : error.resource === "file-size"
@@ -147,7 +147,7 @@ export const analysisErrorUserMessage = (error) => {
     if (standardMessage !== undefined)
         return standardMessage;
     if (error instanceof ArtifactOperationError)
-        return artifactMessage(error.operation, error.reason);
+        return artifactMessage(error);
     if (error instanceof EvidenceReferenceError)
         return error.reason === "missing"
             ? `Evidence ${error.evidenceId} is not retained in this session. Supply complete inline Evidence, re-run its producer, or import its bundle before using this reference.`
@@ -267,17 +267,29 @@ const START_FAILURE_TAGS = new Set([
     "HopperProcessError",
     "HopperStartError",
 ]);
-const artifactMessage = (operation, reason) => {
+/** Operations that accept integrity_policy for declared-integrity mismatches. */
+const INTEGRITY_POLICY_OPERATIONS = new Set([
+    "inventory_artifact",
+    "inspect_artifact",
+    "extract_artifact",
+    "analyze_javascript_application",
+]);
+const artifactMessage = ({ operation, reason, artifactDetails: details, detail, }) => {
     if (reason === "cancelled")
         return "Artifact operation was cancelled. Start it again when ready.";
     if (reason === "limit")
         return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
     if (reason === "path")
-        return "Artifact contains an unsafe or conflicting internal path. Inspect the reported path and correct the artifact before retrying.";
+        return (detail ??
+            "Artifact contains a conflicting internal path. Inspect the reported path before retrying.");
+    if (reason === "unavailable" && details?.unpacked === true)
+        return `ASAR unpacked companion bytes are unavailable for ${details.logicalPath}. Select the archive in place with its .unpacked directory beside it, then retry.`;
     if (reason === "unavailable")
         return "Artifact processing is unavailable for the current target or host. Check artifact support and required tools.";
-    if (reason === "integrity" && operation === "analyze_javascript_application")
-        return "Artifact bytes contradict declared integrity. If expected, rerun analyze_javascript_application with integrity_policy=record-and-continue (CLI: --integrity-policy record-and-continue) to retain observed bytes as untrusted; otherwise get a fresh copy.";
+    if (reason === "integrity" && INTEGRITY_POLICY_OPERATIONS.has(operation))
+        return `${details?.unpacked === true && details.calculatedSha256 !== null
+            ? `Declared ASAR integrity for unpacked entry ${details.logicalPath} contradicts its companion file; packaging tools commonly sign or strip unpacked native binaries after writing the archive.`
+            : "Artifact bytes contradict declared integrity."} If expected, rerun ${operation === "inventory_artifact" ? "inspect_artifact" : operation} with integrity_policy=record-and-continue (CLI: --integrity-policy record-and-continue) to retain observed bytes as untrusted; otherwise get a fresh copy.`;
     if (reason === "format" || reason === "integrity")
         return "Artifact is invalid or has changed. Get a fresh copy and try again.";
     return "Artifact could not be read or written. Check file access and try again.";

package/dist/domain/analysisErrorProjection.js

@@ -1,4 +1,5 @@
 import { jsonValueSchema } from "./jsonValue.js";
+import { isImmutableJsonSnapshot } from "./immutableJson.js";
 import { analysisErrorCategory, analysisErrorRemediationAction, analysisErrorUserMessage, assertKnownAnalysisErrorTag, } from "./analysisErrorPresentation.js";
 import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { ArtifactOperationError } from "./artifactOperationError.js";
@@ -35,7 +36,9 @@ export const projectAnalysisError = (error) => {
         ...(error.partialObservation === undefined
             ? {}
             : {
-                partial_observation: jsonValueSchema.parse(error.partialObservation),
+                partial_observation: isImmutableJsonSnapshot(error.partialObservation)
+                    ? error.partialObservation
+                    : jsonValueSchema.parse(error.partialObservation),
             }),
     };
     return {