rea-agents 6.2.0 → 6.4.0

package/dist/cli/setupCommands.js

@@ -17,6 +17,7 @@ const supportedClientIds = SUPPORTED_CLIENT_DEFINITIONS.map(({ name }) => name);
 const supportedClientSchema = z
     .string()
     .refine((candidate) => supportedClientIds.some((name) => name === candidate), "Unsupported agent integration");
+const skillClientSchema = z.union([z.literal("shared"), supportedClientSchema]);
 /** Register setup, doctor, uninstall, and update CLI commands. */
 export const registerSetupCommands = (cli, logger, environment) => {
     registerSetupCommand(cli, logger, environment);
@@ -40,6 +41,10 @@ const registerSetupCommand = (cli, logger, environment) => {
                 .array(supportedClientSchema)
                 .default([])
                 .describe("Agent integration to configure; repeat for multiple agents"),
+            skillClient: z
+                .array(skillClientSchema)
+                .default([])
+                .describe("Existing client skill destination to update; repeatable"),
             allDetected: z
                 .boolean()
                 .default(false)
@@ -91,7 +96,6 @@ const registerMaintenanceCommands = (cli, logger, environment) => {
                 .default(false)
                 .describe("Also remove REA caches and state"),
         }),
-        alias: { purgeData: "purge-data" },
         run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData, systemUninstallHost(homeDirectoryFromEnvironment(environment, process.platform), undefined, environment)), isUninstallFailure),
     });
     cli.command(CLI_COMMANDS.update, {
@@ -112,8 +116,12 @@ const runSetupCommand = async (input, environment) => {
 };
 const setupRunOptions = (input, interactive, hasExplicitScope) => {
     const { options } = input;
-    const agentIntegrationSelected = options.allDetected || options.client.length > 0;
-    const hasSelectedClients = hasExplicitScope && !options.allDetected;
+    const agentIntegrationSelected = options.allDetected ||
+        options.client.length > 0 ||
+        options.skillClient.length > 0;
+    const hasSelectedClients = hasExplicitScope &&
+        !options.allDetected &&
+        (options.client.length > 0 || options.skillClient.length > 0);
     return {
         approved: options.yes && !options.dryRun,
         installHopper: options.installHopper,
@@ -122,6 +130,9 @@ const setupRunOptions = (input, interactive, hasExplicitScope) => {
         allDetectedClients: options.allDetected,
         proposeHopper: interactive || options.installHopper,
         ...(hasSelectedClients ? { clientIds: options.client } : {}),
+        ...(options.skillClient.length > 0
+            ? { skillClientIds: options.skillClient }
+            : {}),
         ...(hasExplicitScope
             ? { installSkill: options.skill ?? agentIntegrationSelected }
             : {}),
@@ -145,6 +156,7 @@ const setupIsInteractive = (options, formatExplicit) => !options.yes &&
     process.stderr.isTTY === true;
 const setupHasExplicitScope = (options) => options.allDetected ||
     options.client.length > 0 ||
+    options.skillClient.length > 0 ||
     options.skill !== undefined ||
     options.installHopper;
 const doctorScope = (options) => options.client.length === 0 &&

package/dist/cli/streamedJsonOutput.js

@@ -1,18 +1,70 @@
+import { constants } from "node:buffer";
 import {} from "node:stream";
-import { Filter } from "incur";
+import { Cli, Filter } from "incur";
 import { parseCliOutputArguments } from "../cliOutput.js";
-import { writeJsonOutput } from "./jsonOutput.js";
+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError, } from "../domain/analysisErrorProjection.js";
+import { jsonOutputParts, writeJsonOutput } from "./jsonOutput.js";
+const registeredCommands = Cli.toCommands;
+/** Install formatting once, after registration, for every ordinary CLI result. */
+export const streamCliCommandResults = (cli, output) => {
+    const commands = registeredCommands.get(cli);
+    if (commands !== undefined)
+        wrapCommands(commands, [], output);
+};
+const wrapCommands = (commands, parents, output) => {
+    for (const [name, entry] of commands) {
+        const path = [...parents, name];
+        if ("_group" in entry) {
+            wrapCommands(entry.commands, path, output);
+            if (entry.root !== undefined)
+                wrapCommand(entry.root, path.join(" "), output);
+        }
+        else if (!("_alias" in entry) && !("_fetch" in entry))
+            wrapCommand(entry, path.join(" "), output);
+    }
+};
+const wrapCommand = (command, name, output) => {
+    const run = command.run;
+    command.run = (context) => {
+        const started = performance.now();
+        const result = run(context);
+        // Generator results and Incur's sentinel responses retain their own protocol.
+        if (typeof result === "object" &&
+            result !== null &&
+            Symbol.asyncIterator in result)
+            return result;
+        return Promise.resolve(result).then(async (value) => {
+            if (typeof value === "object" &&
+                value !== null &&
+                Symbol.for("incur.sentinel") in value)
+                return value;
+            if (!(await output.write(value, {
+                command: name,
+                format: context.format,
+                duration: `${Math.round(performance.now() - started)}ms`,
+            })))
+                return value;
+            if (output.error !== undefined)
+                return context.error({
+                    code: output.error.code,
+                    message: output.error.message,
+                });
+            return undefined;
+        });
+    };
+};
 /** Preserve Incur's JSON controls while streaming the complete result. */
 export const createStreamedCliJsonOutput = (arguments_, destination) => {
     const options = parseCliOutputArguments(arguments_);
     if (options.parseError ||
-        options.tokenCount ||
         options.tokenWindow ||
         (options.format !== "json" && options.format !== "jsonl"))
         return undefined;
     const format = options.format;
     let handled = false;
     let failed = false;
+    let error;
     return {
         get handled() {
             return handled;
@@ -20,6 +72,9 @@ export const createStreamedCliJsonOutput = (arguments_, destination) => {
         get failed() {
             return failed;
         },
+        get error() {
+            return error;
+        },
         async write(value, metadata) {
             if (metadata.format !== format)
                 return false;
@@ -30,6 +85,26 @@ export const createStreamedCliJsonOutput = (arguments_, destination) => {
                 command: metadata.command,
                 duration: metadata.duration,
             };
+            if (options.tokenCount) {
+                // Incur/tokenx materialize the formatted value. Measure its UTF-16
+                // expansion before allowing that allocation, independently of UTF-8 bytes.
+                let characters = 0;
+                if (filtered !== undefined &&
+                    filtered !== null &&
+                    typeof filtered !== "function" &&
+                    typeof filtered !== "symbol")
+                    for (const part of jsonOutputParts(filtered, format))
+                        characters += part.length;
+                characters = Math.max(0, characters - 1);
+                if (characters <= constants.MAX_STRING_LENGTH)
+                    return false;
+                error = projectAnalysisError(new AnalysisResourceConstraintError(metadata.command, "memory", "Token counting requires a formatted string larger than the runtime permits.", {
+                    formatted_characters: characters,
+                    max_string_characters: constants.MAX_STRING_LENGTH,
+                }, {
+                    remediationAction: "Remove --token-count to stream the complete JSON result, or narrow it with --filter-output.",
+                }));
+            }
             const document = options.fullOutput
                 ? filtered === undefined
                     ? { ok: true, meta }
@@ -44,7 +119,11 @@ export const createStreamedCliJsonOutput = (arguments_, destination) => {
             // document from Incur's error formatter.
             handled = true;
             try {
-                await writeJsonOutput(document, destination, format);
+                await writeJsonOutput(error === undefined
+                    ? document
+                    : options.fullOutput
+                        ? { ok: false, error, meta }
+                        : error, destination, format);
             }
             catch (cause) {
                 failed = true;

package/dist/cli/utilityCommands.js

@@ -1,4 +1,6 @@
 import { z } from "incur";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
 import { importReferenceSource } from "../application/ReferenceSourceImport.js";
 import { projectReferenceSourceImportError } from "../application/ReferenceSourceImportTypes.js";
 import { parseConfig } from "../config/parseConfig.js";
@@ -54,10 +56,6 @@ export const registerUtilityCommands = (cli, logger, environment, analysis) => {
                     .default(500)
                     .describe("Maximum accessibility nodes per capture"),
             }),
-            alias: {
-                windowId: "window-id",
-                maxNodes: "max-nodes",
-            },
             run: ({ args, options }) => logCliCommand(logger, command, async () => {
                 const parameters = {
                     pid: options.pid,
@@ -97,7 +95,7 @@ const invalidNativeUiScenarioInput = (operation, issues) => ({
     error: "Application workflow failed",
     ...projectAnalysisError(new AnalysisInputError(operation, undefined, issues)),
 });
-const registerCapabilityCommands = (cli, logger, { runProviderStatus, runCapabilityStatus, }) => {
+const registerCapabilityCommands = (cli, logger, { runSessionStatus }) => {
     for (const command of [
         CLI_COMMANDS.capabilities,
         CLI_COMMANDS.providers,
@@ -106,9 +104,7 @@ const registerCapabilityCommands = (cli, logger, { runProviderStatus, runCapabil
             description: command === "capabilities"
                 ? "List provider capabilities and side effects"
                 : "List configured analysis providers",
-            run: () => logCliCommand(logger, command, () => command === CLI_COMMANDS.providers
-                ? runProviderStatus(logger)
-                : runCapabilityStatus(logger)),
+            run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
         });
     }
 };
@@ -131,9 +127,8 @@ const registerNativeCommands = (cli, logger, runProviderAnalysis) => {
             relativePath: z
                 .string()
                 .optional()
-                .describe("Plist path relative to the app root (default: Contents/Info.plist)"),
+                .describe("Plist path relative to the app root, or an absolute path (default: the bundle's Info.plist)"),
         }),
-        alias: { relativePath: "relative-path" },
         run: ({ args, options }) => logCliCommand(logger, "inspect-plist", () => runProviderAnalysis(args.path, "inspect_plist", options.relativePath === undefined
             ? {}
             : { path: options.relativePath }, logger)),
@@ -162,19 +157,70 @@ const registerReferenceSourceCommand = (cli, logger, environment) => {
                     error: "Import failed",
                     ...projectAnalysisError(config.error),
                 };
-            const imported = await importReferenceSource({
-                root: args.root,
+            return runReferenceSourceImport(args.root, config.value.referenceSourcePolicy);
+        }, isReferenceSourceImportCliFailure),
+    });
+};
+const runReferenceSourceImport = async (root, policy) => {
+    const resources = new ArtifactResourceScope();
+    let outcome;
+    try {
+        outcome = {
+            kind: "result",
+            imported: await importReferenceSource({
+                root,
                 caller: "rea-cli",
-                policy: config.value.referenceSourcePolicy,
+                policy,
                 importer: PRODUCT_IDENTITY.packageName,
                 importerVersion: null,
-            });
-            return imported.ok
-                ? imported.value
-                : {
-                    error: "Import failed",
-                    ...projectReferenceSourceImportError(imported.error),
-                };
-        }, isReferenceSourceImportCliFailure),
-    });
+            }, resources),
+        };
+    }
+    catch (cause) {
+        outcome = { kind: "thrown", cause };
+    }
+    let closeOutcome;
+    try {
+        await resources.close();
+        closeOutcome = { kind: "closed" };
+    }
+    catch (cause) {
+        closeOutcome = { kind: "failed", cause };
+    }
+    if (outcome.kind === "thrown") {
+        if (closeOutcome.kind === "failed")
+            throw new AggregateError([outcome.cause, closeOutcome.cause], "Reference source import and cleanup both failed", { cause: outcome.cause });
+        throw outcome.cause;
+    }
+    const imported = outcome.imported;
+    if (!imported.ok) {
+        const cleanup = closeOutcome.kind === "closed"
+            ? imported.error.cleanup
+            : mergeReferenceSourceCleanup(imported.error.cleanup, ArtifactReaderFailure.cleanupObservation(closeOutcome.cause, "reference source"));
+        return {
+            error: "Import failed",
+            ...projectReferenceSourceImportError({
+                ...imported.error,
+                ...(cleanup === undefined ? {} : { cleanup }),
+            }),
+        };
+    }
+    if (closeOutcome.kind === "failed")
+        return {
+            error: "Import failed",
+            ...projectReferenceSourceImportError({
+                tag: "reference-source-import",
+                code: "io",
+                message: "Reference source cleanup failed after import",
+                cleanup: ArtifactReaderFailure.cleanupObservation(closeOutcome.cause, "reference source"),
+                cause: closeOutcome.cause,
+            }),
+        };
+    return imported.value;
 };
+const mergeReferenceSourceCleanup = (first, second) => first === undefined
+    ? second
+    : {
+        reason: `${first.reason}; ${second.reason}`,
+        resources: [...new Set([...first.resources, ...second.resources])],
+    };

package/dist/cli/webScriptCommands.js

@@ -1,8 +1,12 @@
 import { Cli, z } from "incur";
 import { exportWebScripts } from "../application/WebScriptExportService.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 /** Register the local captured-script export CLI workflow. */
 export const registerWebScriptCommands = (cli, logger) => {
     cli.command(CLI_COMMANDS.exportWebScripts, {
@@ -16,10 +20,25 @@ export const registerWebScriptCommands = (cli, logger) => {
                 .describe("Absolute absent directory for verified scripts and manifest"),
         }),
         run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.exportWebScripts, async () => {
+            const resources = new ArtifactResourceScope();
             const result = await exportWebScripts({
                 capture_path: args.capturePath,
                 output_directory: args.outputDirectory,
-            });
+            }, resources);
+            try {
+                await resources.close();
+            }
+            catch (cause) {
+                const cleanup = ArtifactReaderFailure.cleanupObservation(cause, "Web script export resources");
+                const failure = new ProviderCleanupError("web-script-export", cleanup.resources, { reason: cleanup.reason }, { cause, operation: "export_web_scripts" });
+                const error = result.ok
+                    ? failure
+                    : analysisErrorWithCleanupFailure(result.error, failure, "export_web_scripts");
+                return {
+                    error: "Script export failed",
+                    ...projectAnalysisError(error),
+                };
+            }
             return result.ok
                 ? result.value
                 : {

package/dist/cli/webSourceLocationCommands.js

@@ -29,14 +29,26 @@ export const registerWebSourceLocationCommands = (cli, logger, environment) => {
                 .min(0)
                 .describe("Zero-based UTF-16 generated column"),
         }),
-        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.traceWebSourceLocation, async () => {
-            const result = await service.trace({
-                manifest_path: args.manifestPath,
-                script_index: args.scriptIndex,
-                source_map: { path: args.sourceMapPath, url: args.sourceMapUrl },
-                generated_position: { line: args.line, column: args.column },
-            }, { signal });
-            return result.ok ? result.value : projectAnalysisError(result.error);
-        })),
+        run: ({ args }) => withCommandCancellation(async (signal) => {
+            try {
+                return await logCliCommand(logger, CLI_COMMANDS.traceWebSourceLocation, async () => {
+                    const result = await service.trace({
+                        manifest_path: args.manifestPath,
+                        script_index: args.scriptIndex,
+                        source_map: {
+                            path: args.sourceMapPath,
+                            url: args.sourceMapUrl,
+                        },
+                        generated_position: { line: args.line, column: args.column },
+                    }, { signal });
+                    return result.ok
+                        ? result.value
+                        : projectAnalysisError(result.error);
+                });
+            }
+            finally {
+                await service.close();
+            }
+        }),
     });
 };

package/dist/cli.js

@@ -14,6 +14,9 @@ import { registerArtifactCommands } from "./cli/artifactCommands.js";
 import { registerManagedCommands } from "./cli/managedCommands.js";
 import { registerFirmwareCommands } from "./cli/firmwareCommands.js";
 import { registerAndroidCommands } from "./cli/androidCommands.js";
+import { registerApktoolCommands } from "./cli/apktoolCommands.js";
+import { registerJebCommands } from "./cli/jebCommands.js";
+import { registerAdbCommands } from "./cli/adbCommands.js";
 import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
 import { registerProcessCommands } from "./cli/processCommands.js";
 import { registerBrowserCommands } from "./cli/browserCommands.js";
@@ -29,6 +32,7 @@ import { registerElectronCommands } from "./cli/electronCommands.js";
 import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRuntimeCommands.js";
 import { registerApplicationCommands } from "./cli/applicationCommands.js";
 import { presentOmittableDefaults } from "./cli/omittableDefaults.js";
+import { streamCliCommandResults, } from "./cli/streamedJsonOutput.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
@@ -50,12 +54,15 @@ export const createCli = (selectedEnvironment = process.env, resultOutput) => {
         sync: false,
     });
     registerSetupCommands(cli, logger, environment);
-    registerCoreAnalysisCommands(cli, logger, analysis.runDirectAnalysis, resultOutput);
+    registerCoreAnalysisCommands(cli, logger, analysis.runDirectAnalysis);
     registerUtilityCommands(cli, logger, environment, analysis);
     registerEvmCommands(cli, logger, environment);
     registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);
     registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
     registerAndroidCommands(cli, logger, environment);
+    registerApktoolCommands(cli, logger, environment);
+    registerJebCommands(cli, logger, environment);
+    registerAdbCommands(cli, logger, environment);
     registerFirmwareCommands(cli, logger, environment);
     registerBinaryDiagnosticsCommands(cli, logger, environment);
     registerAnalysisViewCommands(cli, logger);
@@ -70,9 +77,11 @@ export const createCli = (selectedEnvironment = process.env, resultOutput) => {
     registerJavaScriptRecoveryCommands(cli, logger, environment);
     registerAdvancedBrowserCommands(cli, logger);
     registerBrowserScenarioCommands(cli, logger, environment);
-    registerElectronCommands(cli, logger, environment, resultOutput);
+    registerElectronCommands(cli, logger, environment);
     registerJavaScriptRuntimeObservationCommands(cli, logger);
     registerApplicationCommands(cli, logger);
     presentOmittableDefaults(cli);
+    if (resultOutput !== undefined)
+        streamCliCommandResults(cli, resultOutput);
     return cli;
 };

package/dist/cliBrowserScenarioCommands.js

@@ -1,7 +1,6 @@
 import { Cli } from "incur";
 import { z } from "zod";
 import { captureBrowserScenario } from "./application/BrowserScenarioCaptureService.js";
-import { createBrowserScenarioProvider } from "./composition/browserScenario.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { parseCliJsonInput, resolveCliJsonPaths } from "./cliJsonInput.js";
 import { logCliCommand } from "./cliLogging.js";
@@ -26,6 +25,8 @@ export const registerBrowserScenarioCommands = (cli, logger, environment) => {
             const scenario = browserScenarioSchema.safeParse(resolveCliJsonPaths(input.value, [["browser", "executable_path"]]));
             if (!scenario.success)
                 return cliError(new AnalysisInputError(OPERATION, { cause: scenario.error }, projectInputIssues(scenario.error.issues, input.value)));
+            // Load Playwright only for this command, not during CLI startup.
+            const { createBrowserScenarioProvider } = await import("./composition/browserScenario.js");
             const result = await captureBrowserScenario(createBrowserScenarioProvider(environment), scenario.data);
             return result.ok ? result.value : cliError(result.error);
         }),

package/dist/cliCommandNames.js

@@ -41,14 +41,46 @@ export const CLI_COMMANDS = Object.freeze({
     inspectManagedArtifact: "inspect-managed-artifact",
     inspectRecordedCrash: "inspect-recorded-crash",
     inspectBinaryLayout: "inspect-binary-layout",
+    inspectPeResources: "inspect-pe-resources",
     inspectAnalysisView: "inspect-analysis-view",
+    inspectEvidenceBundle: "inspect-evidence-bundle",
     inspectFirmwareRegions: "inspect-firmware-regions",
     extractFirmware: "extract-firmware",
     inspectAndroidPackage: "inspect-android-package",
+    inspectApktoolClient: "inspect-apktool-client",
+    decodeAndroidResources: "decode-android-resources",
+    inspectAdbClient: "inspect-adb-client",
+    listAdbDevices: "list-adb-devices",
+    inspectAdbDevice: "inspect-adb-device",
+    listAdbPackages: "list-adb-packages",
+    pullAdbPackage: "pull-adb-package",
+    readAdbLogcat: "read-adb-logcat",
+    inspectAdbPackage: "inspect-adb-package",
+    pullAdbFile: "pull-adb-file",
+    pushAdbFile: "push-adb-file",
+    captureAdbScreen: "capture-adb-screen",
+    listAdbProcesses: "list-adb-processes",
+    listAdbDirectory: "list-adb-directory",
+    listAdbFeatures: "list-adb-features",
+    listAdbServices: "list-adb-services",
+    inspectAdbDisplay: "inspect-adb-display",
+    inspectAdbWindow: "inspect-adb-window",
+    readAdbSetting: "read-adb-setting",
+    collectAdbBugreport: "collect-adb-bugreport",
+    resolveAdbPackages: "resolve-adb-packages",
+    installAdbPackage: "install-adb-package",
+    uninstallAdbPackage: "uninstall-adb-package",
+    startAdbApp: "start-adb-app",
+    startAdbActivity: "start-adb-activity",
+    stopAdbApp: "stop-adb-app",
     searchAndroidClasses: "search-android-classes",
     inspectAndroidClass: "inspect-android-class",
     inspectAndroidMethod: "inspect-android-method",
     traceAndroidReferences: "trace-android-references",
+    inspectJebClient: "inspect-jeb-client",
+    openJebProject: "open-jeb-project",
+    listJebUnits: "list-jeb-units",
+    decompileJebItem: "decompile-jeb-item",
     inspectManagedMembers: "inspect-managed-members",
     inspectManagedNativeBoundaries: "inspect-managed-native-boundaries",
     compareManagedMembers: "compare-managed-members",

package/dist/cliJsonInput.js

@@ -1,29 +1,52 @@
-import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { AnalysisInputError } from "./domain/analysisErrorCore.js";
+import { readJsonInputFile } from "./application/JsonInputFile.js";
+import { NonRegularFileReadError } from "./filesystem/RegularFile.js";
+import { AnalysisAccessDeniedError, AnalysisInputError, } from "./domain/analysisErrorCore.js";
 import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
 import { safeParseJson } from "./domain/safeJson.js";
 /** Parse inline JSON or one local JSON file for a CLI workflow. */
 export const parseCliJsonInput = async (value, operation) => {
-    const inline = parseJson(value);
-    if (inline !== undefined)
-        return { ok: true, value: inline };
+    const inline = safeParseJson(value);
+    if (inline.ok)
+        return { ok: true, value: inline.value };
     try {
-        // Read raw bytes so invalid UTF-8 is rejected by parseJson instead of
-        // being silently replaced by lossy "utf8" decoding.
-        const parsed = parseJson(await readFile(value));
-        return parsed === undefined
-            ? jsonFileError(value, operation, "invalid-json")
-            : { ok: true, value: parsed };
+        const parsed = await readJsonInputFile(value, operation);
+        return parsed.ok
+            ? { ok: true, value: parsed.value }
+            : {
+                ok: false,
+                error: {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(parsed.error),
+                    input_path: value,
+                    input_reason: parsed.error._tag === "AnalysisInputError"
+                        ? "invalid-json"
+                        : "too-large",
+                },
+            };
     }
     catch (cause) {
+        const systemCode = accessDeniedSystemCode(cause);
+        if (systemCode !== undefined)
+            return jsonAccessDeniedError(value, operation, systemCode, cause);
         if (["{", "["].includes(value.trimStart()[0] ?? "") &&
             cannotBeAnExistingFile(cause) &&
             !hasExplicitJsonFileExtension(value))
             return { ok: false, error: inputError(operation) };
+        if (!(cause instanceof Error) ||
+            !("code" in cause) ||
+            typeof cause.code !== "string")
+            throw cause;
         return jsonFileError(value, operation, "read-failed", cause);
     }
 };
+const accessDeniedSystemCode = (cause) => {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return undefined;
+    return cause.code === "EACCES" || cause.code === "EPERM"
+        ? cause.code
+        : undefined;
+};
 /**
  * Resolve named string fields of CLI-supplied JSON against the operator
  * working directory. Each entry is a key path from the document root; only
@@ -62,27 +85,6 @@ const cannotBeAnExistingFile = (cause) => typeof cause === "object" &&
         cause.code === "ENAMETOOLONG" ||
         cause.code === "ENOTDIR");
 const hasExplicitJsonFileExtension = (value) => value.toLowerCase().endsWith(".json");
-const parseJson = (value) => {
-    let text;
-    if (typeof value === "string") {
-        text = value;
-    }
-    else {
-        try {
-            text = new TextDecoder("utf-8", {
-                fatal: true,
-                ignoreBOM: true,
-            }).decode(value);
-        }
-        catch (cause) {
-            // Decoding failure means the bytes are not valid UTF-8 JSON input.
-            void cause;
-            return undefined;
-        }
-    }
-    const parsed = safeParseJson(text);
-    return parsed.ok ? parsed.value : undefined;
-};
 const inputError = (operation) => ({
     error: "Application workflow failed",
     ...projectAnalysisError(new AnalysisInputError(operation, undefined, [
@@ -100,7 +102,16 @@ const jsonFileError = (path, operation, reason, cause) => ({
         input_reason: reason,
     },
 });
-/** Name the system error so the caller can tell a typo from a permission denial. */
+const jsonAccessDeniedError = (path, operation, systemCode, cause) => ({
+    ok: false,
+    error: {
+        error: "Application workflow failed",
+        ...projectAnalysisError(new AnalysisAccessDeniedError(operation, path, systemCode, { cause })),
+        input_path: path,
+        input_reason: "read-failed",
+    },
+});
+/** Preserve file-selection and system failures alongside the requested path. */
 const readFailureIssue = (path, cause) => {
     const code = typeof cause === "object" &&
         cause !== null &&
@@ -111,6 +122,8 @@ const readFailureIssue = (path, cause) => {
     return {
         path: [],
         reason: "invalid_value",
-        message: `The JSON input file could not be read${code}: ${path ?? ""}`,
+        message: cause instanceof NonRegularFileReadError && cause.code === "ENOTFILE"
+            ? `The JSON input must be a regular file${code}: ${path ?? ""}`
+            : `The JSON input file could not be read${code}: ${path ?? ""}`,
     };
 };

package/dist/cliObservationOptions.js

@@ -1,4 +1,5 @@
 import { z } from "incur";
+import { javaScriptAnalysisResourceControlsSchema } from "./domain/javascript/javascriptAnalysisResourceControls.js";
 /** Accept an agent-selected browser observation duration without an artificial ceiling. */
 export const observationDuration = (fallback, minimum = 0) => z
     .number()
@@ -53,8 +54,14 @@ export const electronPageInspectionOptions = z.object({
         .describe("Include JavaScript source text"),
 });
 export const javascriptApplicationOptions = z.object({
+    maxHeapMb: javaScriptAnalysisResourceControlsSchema.shape.max_heap_mb,
+    analysisTimeoutMs: javaScriptAnalysisResourceControlsSchema.shape.analysis_timeout_ms,
     artifactFormat: z
         .enum(["auto", "asar", "directory"])
         .default("auto")
         .describe("Application artifact format"),
+    integrityPolicy: z
+        .enum(["fail", "record-and-continue"])
+        .default("fail")
+        .describe("Behavior when declared application integrity does not match"),
 });

package/dist/composition/adb.js

@@ -0,0 +1,3 @@
+import { AdbProvider } from "../adb/AdbProvider.js";
+/** Construct one ADB provider bound to the caller-selected binary. */
+export const createAdbDeviceAnalysisProvider = (environment = process.env) => new AdbProvider({ environment });

package/dist/composition/apktool.js

@@ -0,0 +1,3 @@
+import { ApktoolProvider } from "../apktool/ApktoolProvider.js";
+/** Construct one Apktool provider bound to the caller-selected launcher. */
+export const createApktoolResourceAnalysisProvider = (environment = process.env) => new ApktoolProvider({ environment });