rea-agents 6.4.0 → 6.5.0

package/dist/cli/coreBinaryCommands.js

@@ -4,10 +4,11 @@ import { resolve } from "node:path";
 import { resolveCliAnalysisSelector } from "./analysisSelector.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
-import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
+import { directAnalysisOptionsFromCli, nativeOpenOptionFields, } from "./options.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 import { withCommandCancellation } from "./commandCancellation.js";
 import { javascriptApplicationOptions } from "../cliObservationOptions.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 /** Register provider-neutral binary overview and procedure CLI commands. */
 export const registerCoreBinaryCommands = (cli, logger, runDirectAnalysis) => {
     registerOverviewCommands(cli, logger, runDirectAnalysis);
@@ -25,16 +26,35 @@ const registerOverviewCommands = (cli, logger, runDirectAnalysis) => {
             .min(1)
             .optional()
             .describe("Load and update a local analysis snapshot"),
-        "target-format": formatSelectionOption,
-        provider: providerSelectionOption,
+        ...nativeOpenOptionFields,
     });
+    // `analyze` declares the JavaScript integrity policy for its JavaScript
+    // lane. Preserve whether the caller supplied it until the target lane is
+    // known, then apply the JavaScript default only in that lane. The owner
+    // field fills an omission with that default, and an `.optional()` wrapper
+    // keeps reporting it, so every binary target would look like an explicit
+    // policy. Remove the owner's default before making the CLI option optional;
+    // reapply its metadata so help and `--schema` keep describing the option.
+    const ownerIntegrityPolicy = javascriptApplicationOptions.shape.integrityPolicy;
+    const defaultIntegrityPolicy = ownerIntegrityPolicy.parse(undefined);
+    const policyMetadata = ownerIntegrityPolicy.meta();
+    const omittableIntegrityPolicy = ownerIntegrityPolicy
+        .removeDefault()
+        .optional();
+    const laneIntegrityPolicy = policyMetadata === undefined
+        ? omittableIntegrityPolicy
+        : omittableIntegrityPolicy.meta(policyMetadata);
     cli.command(CLI_COMMANDS.analyze, {
         description: "Get an overview of an app",
         args: z.object({
-            path: z.string().describe("App, program, or analysis database path"),
+            path: z
+                .string()
+                .min(1)
+                .describe("App, program, or analysis database path"),
         }),
         options: overviewOptions.extend({
-            integrityPolicy: javascriptApplicationOptions.shape.integrityPolicy,
+            integrityPolicy: laneIntegrityPolicy,
+            sourcePath: javascriptApplicationOptions.shape.sourcePath,
         }),
         run: async ({ args, options }) => {
             // Route JavaScript targets exactly like analyze-javascript-application,
@@ -43,9 +63,30 @@ const registerOverviewCommands = (cli, logger, runDirectAnalysis) => {
             if (await routesToJavaScriptAnalysis(args.path, options))
                 return withCommandCancellation((signal) => logCliCommand(logger, "analyze", () => runCliJavaScriptApplicationAnalysis({
                     input_path: resolve(args.path),
-                    integrity_policy: options.integrityPolicy,
+                    integrity_policy: options.integrityPolicy ?? defaultIntegrityPolicy,
+                    ...(options.sourcePath === undefined
+                        ? {}
+                        : { source_paths: options.sourcePath }),
                 }, signal)));
-            return logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"])));
+            return logCliCommand(logger, "analyze", () => {
+                if (options.sourcePath !== undefined)
+                    throw new AnalysisInputError("analyze_javascript_application", undefined, [
+                        {
+                            path: ["source_paths"],
+                            reason: "invalid_value",
+                            message: "Source selection requires the static JavaScript ASAR/directory analysis lane.",
+                        },
+                    ]);
+                if (options.integrityPolicy !== undefined)
+                    throw new AnalysisInputError("analyze_javascript_application", undefined, [
+                        {
+                            path: ["integrity_policy"],
+                            reason: "invalid_value",
+                            message: "An integrity policy requires the static JavaScript ASAR/directory analysis lane; binary_overview accepts no input.",
+                        },
+                    ]);
+                return runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptionsFromCli(logger, options));
+            });
         },
     });
     cli.command(CLI_COMMANDS.inspect, {
@@ -54,7 +95,7 @@ const registerOverviewCommands = (cli, logger, runDirectAnalysis) => {
             path: z.string().describe("App, program, or analysis database path"),
         }),
         options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerDecompileCommand = (cli, logger, runDirectAnalysis) => {
@@ -74,23 +115,33 @@ const registerDecompileCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
+            "file-offset": z
+                .string()
+                .regex(/^0x[0-9a-fA-F]+$/u)
+                .optional()
+                .describe("Ghidra source-file byte offset; mapped internally to an analysis address"),
             snapshot: z
                 .string()
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", {
-            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "procedure_pseudo_code"),
-        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+            procedure: resolveCliAnalysisSelector(args.address, options["file-offset"] === undefined
+                ? options.procedure
+                : resolveCliAnalysisSelector(options.procedure, `file-offset:${options["file-offset"]}`, "file-offset", "procedure_pseudo_code"), options["file-offset"] === undefined
+                ? "procedure"
+                : "file-offset", "procedure_pseudo_code"),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 /** Select static JavaScript analysis only when no binary-analysis option applies. */
 const routesToJavaScriptAnalysis = async (path, options) => options.provider === undefined &&
     options.snapshot === undefined &&
     options["target-format"] === undefined &&
+    options.architecture === undefined &&
+    options["entry-point"] === undefined &&
     (await isJavaScriptApplicationPath(path));
 const isJavaScriptApplicationPath = async (path) => {
     const lower = path.toLowerCase();
@@ -126,12 +177,11 @@ const registerXrefsCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", {
             address: resolveCliAnalysisSelector(args.address, options.address, "address", "xrefs"),
-        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerTraceCommand = (cli, logger, runDirectAnalysis) => {
@@ -156,13 +206,12 @@ const registerTraceCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, "trace", () => runDirectAnalysis(args.path, "trace_feature", {
             query: resolveCliAnalysisSelector(args.query, options.query, "query", "trace_feature"),
             case_sensitive: options.caseSensitive,
-        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerFunctionCommand = (cli, logger, runDirectAnalysis) => {
@@ -187,12 +236,11 @@ const registerFunctionCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", {
             procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "analyze_function"),
-        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerInstructionsCommand = (cli, logger, runDirectAnalysis) => {
@@ -217,12 +265,11 @@ const registerInstructionsCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.instructions, () => runDirectAnalysis(args.path, "read_function_instructions", {
             procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "read_function_instructions"),
-        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerSearchCommand = (cli, logger, runDirectAnalysis) => {
@@ -259,8 +306,7 @@ const registerSearchCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, "search", () => runDirectAnalysis(args.path, options.kind === "strings" ? "search_strings" : "search_procedures", {
             pattern: resolveCliAnalysisSelector(args.pattern, options.pattern, "pattern", options.kind === "strings"
@@ -268,6 +314,6 @@ const registerSearchCommand = (cli, logger, runDirectAnalysis) => {
                 : "search_procedures"),
             mode: options.mode,
             case_sensitive: options.caseSensitive,
-        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };

package/dist/cli/coreNativeCommands.js

@@ -1,18 +1,49 @@
 import { z } from "incur";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
-import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
+import { directAnalysisOptionsFromCli, nativeOpenOptionFields, } from "./options.js";
 /** Register native load-image, memory, and annotation CLI commands. */
 export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
     registerAnnotationCommand(cli, logger, runDirectAnalysis);
+    cli.command(CLI_COMMANDS.searchBytes, {
+        description: "Find masked byte patterns in initialized provider memory",
+        args: z.object({
+            path: z.string().describe("Local executable path"),
+            pattern: z.string().describe("Hexadecimal byte pairs with ?? wildcards"),
+        }),
+        options: z.object({
+            mask: z.string().optional().describe("Equal-length hexadecimal bit mask"),
+            start: z.string().optional().describe("Inclusive start address"),
+            end: z.string().optional().describe("Inclusive end address"),
+            cursor: z
+                .string()
+                .optional()
+                .describe("Continuation from the same query's next_cursor"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(1000)
+                .default(100)
+                .describe("Maximum matches on this page"),
+            ...nativeOpenOptionFields,
+        }),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.searchBytes, () => runDirectAnalysis(args.path, "search_bytes", {
+            pattern: args.pattern,
+            limit: options.limit,
+            ...(options.mask === undefined ? {} : { mask: options.mask }),
+            ...(options.start === undefined ? {} : { start: options.start }),
+            ...(options.end === undefined ? {} : { end: options.end }),
+            ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+        }, directAnalysisOptionsFromCli(logger, options))),
+    });
     cli.command(CLI_COMMANDS.inspectNativeLoadImage, {
         description: "Verify loaded native bytes, source mappings, relocations and entry",
         args: z.object({ path: z.string().describe("Local executable path") }),
         options: z.object({
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
-        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.inspectNativeLoadImage, () => runDirectAnalysis(args.path, "inspect_native_load_image", {}, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.inspectNativeLoadImage, () => runDirectAnalysis(args.path, "inspect_native_load_image", {}, directAnalysisOptionsFromCli(logger, options))),
     });
     cli.command(CLI_COMMANDS.readBytes, {
         description: "Read exact provider memory bytes at one analysis address",
@@ -27,10 +58,9 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .default(256)
                 .describe("Requested byte count"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
-        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.readBytes, () => runDirectAnalysis(args.path, "read_bytes", { address: args.address, length: options.length }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.readBytes, () => runDirectAnalysis(args.path, "read_bytes", { address: args.address, length: options.length }, directAnalysisOptionsFromCli(logger, options))),
     });
     cli.command(CLI_COMMANDS.addressToFileOffset, {
         description: "Resolve an analysis address to its original file byte offset",
@@ -39,10 +69,9 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
             address: z.string().describe("Exact provider memory address"),
         }),
         options: z.object({
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
-        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.addressToFileOffset, () => runDirectAnalysis(args.path, "address_to_file_offset", { address: args.address }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.addressToFileOffset, () => runDirectAnalysis(args.path, "address_to_file_offset", { address: args.address }, directAnalysisOptionsFromCli(logger, options))),
     });
     cli.command(CLI_COMMANDS.traceNativeValues, {
         description: "Trace bounded native def-use and call dependencies",
@@ -101,8 +130,7 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
                 .max(5000)
                 .default(1000)
                 .describe("Maximum nodes on this page"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.traceNativeValues, () => runDirectAnalysis(args.path, "trace_native_values", {
             procedure: args.procedure,
@@ -113,7 +141,7 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
             max_edges: options.maxEdges,
             offset: options.offset,
             limit: options.limit,
-        }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
     cli.command(CLI_COMMANDS.inspectNativeDataType, {
         description: "Inspect one recovered database type or typed data object",
@@ -123,15 +151,14 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
         options: z.object({
             type: z.string().optional().describe("Exact database type category path"),
             address: z.string().optional().describe("Exact native address"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.inspectNativeDataType, () => runDirectAnalysis(args.path, "inspect_native_data_type", {
             ...(options.type === undefined ? {} : { type: options.type }),
             ...(options.address === undefined
                 ? {}
                 : { address: options.address }),
-        }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
     for (const [command, operation] of [
         [CLI_COMMANDS.inspectNativeInstruction, "inspect_native_instruction"],
@@ -146,10 +173,9 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
                 address: z.string().describe("Exact native address"),
             }),
             options: z.object({
-                "target-format": formatSelectionOption,
-                provider: providerSelectionOption,
+                ...nativeOpenOptionFields,
             }),
-            run: ({ args, options }) => logCliCommand(logger, command, () => runDirectAnalysis(args.path, operation, { address: args.address }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+            run: ({ args, options }) => logCliCommand(logger, command, () => runDirectAnalysis(args.path, operation, { address: args.address }, directAnalysisOptionsFromCli(logger, options))),
         });
     }
     registerNativeApiCommand(cli, logger, runDirectAnalysis);
@@ -175,10 +201,9 @@ const registerNativeDispatchMetadataCommand = (cli, logger, runDirectAnalysis) =
                 .min(1)
                 .optional()
                 .describe("Load or update the local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
-        run: async ({ args, options }) => logCliCommand(logger, "inspect-native-dispatch-metadata", () => runDirectAnalysis(args.path, "inspect_native_dispatch_metadata", { max_records: options.maxRecords }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: async ({ args, options }) => logCliCommand(logger, "inspect-native-dispatch-metadata", () => runDirectAnalysis(args.path, "inspect_native_dispatch_metadata", { max_records: options.maxRecords }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerNativeUiActionCommand = (cli, logger, runDirectAnalysis) => {
@@ -213,15 +238,14 @@ const registerNativeUiActionCommand = (cli, logger, runDirectAnalysis) => {
                 .max(5_000)
                 .default(500)
                 .describe("Maximum returned graph edges"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: async ({ args, options }) => logCliCommand(logger, "trace-native-ui-action", () => runDirectAnalysis(args.path, "trace_native_ui_action", {
             action: args.action,
             max_depth: options.maxDepth,
             max_nodes: options.maxNodes,
             max_edges: options.maxEdges,
-        }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerNativeApiCommand = (cli, logger, runDirectAnalysis) => {
@@ -237,10 +261,9 @@ const registerNativeApiCommand = (cli, logger, runDirectAnalysis) => {
                 .min(1)
                 .optional()
                 .describe("Load and update a local analysis snapshot"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", { procedure: args.address }, directAnalysisOptionsFromCli(logger, options))),
     });
 };
 const registerAnnotationCommand = (cli, logger, runDirectAnalysis) => {
@@ -262,8 +285,7 @@ const registerAnnotationCommand = (cli, logger, runDirectAnalysis) => {
                 .string()
                 .optional()
                 .describe("Inline entry comment; empty text clears it"),
-            "target-format": formatSelectionOption,
-            provider: providerSelectionOption,
+            ...nativeOpenOptionFields,
         }),
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.annotateNativeFunction, () => runDirectAnalysis(args.path, "annotate_native_function", {
             procedure: args.procedure,
@@ -274,6 +296,6 @@ const registerAnnotationCommand = (cli, logger, runDirectAnalysis) => {
             ...(options["inline-comment"] === undefined
                 ? {}
                 : { inline_comment: options["inline-comment"] }),
-        }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
+        }, directAnalysisOptionsFromCli(logger, options))),
     });
 };

package/dist/cli/cutterCommands.js

@@ -0,0 +1,50 @@
+import { z } from "incur";
+import { CutterBridgeClient } from "../cutter/CutterBridgeClient.js";
+import { CutterBridgeService } from "../cutter/CutterBridgeService.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Register commands that control an already-running Cutter instance. */
+export const registerCutterCommands = (cli, logger, environment) => {
+    const cutter = new CutterBridgeService(new CutterBridgeClient(environment));
+    cli.command(CLI_COMMANDS.listCutterSessions, {
+        description: "List live Cutter instances connected through the REA Python plugin bridge",
+        args: z.object({}),
+        run: () => logCliCommand(logger, CLI_COMMANDS.listCutterSessions, () => cutter.listSessions()),
+    });
+    cli.command(CLI_COMMANDS.cutterCommand, {
+        description: "Execute one Rizin command in a selected live Cutter instance",
+        args: z.object({
+            sessionId: z
+                .string()
+                .uuid()
+                .describe("Session ID copied from list-cutter-sessions."),
+            expectedGeneration: z.coerce
+                .number()
+                .int()
+                .nonnegative()
+                .describe("Session generation returned by list-cutter-sessions."),
+            command: z
+                .string()
+                .min(1)
+                .describe("One unrestricted Rizin command to run in Cutter.")
+                .refine((value) => !/[\r\n]/u.test(value)),
+        }),
+        options: z.object({
+            json: z
+                .boolean()
+                .default(false)
+                .describe("Return command-specific JSON output when available."),
+        }),
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.cutterCommand, async () => {
+            const result = await cutter.execute({
+                session_id: args.sessionId,
+                expected_generation: args.expectedGeneration,
+                command: args.command,
+                json: options.json,
+            }, { signal });
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        })),
+    });
+};

package/dist/cli/electronCommands.js

@@ -1,7 +1,5 @@
+import { isAbsolute, resolve, sep } from "node:path";
 import { Cli, z } from "incur";
-import { inspectElectronPage, listElectronTargets, } from "../application/javascript/ElectronObservationService.js";
-import { captureElectronScenario } from "../application/javascript/ElectronActiveObservationService.js";
-import { reconcileJavaScriptRuntimeEvidence } from "../application/javascript/JavaScriptRuntimeReconciliationService.js";
 import { logCliCommand } from "../cliLogging.js";
 import { inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/javascript/electronObservation.js";
 import { electronActiveObservationInputSchema } from "../domain/javascript/electronActiveObservation.js";
@@ -9,6 +7,7 @@ import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { createElectronFuseService } from "../composition/electronFuses.js";
 import { parseCliJsonInput, resolveCliJsonPaths } from "../cliJsonInput.js";
 import { electronPageInspectionOptions, javascriptApplicationOptions, } from "../cliObservationOptions.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
@@ -16,10 +15,38 @@ import { withCommandCancellation } from "./commandCancellation.js";
 /** Register CLI equivalents of the Electron MCP tools. */
 export const registerElectronCommands = (cli, logger, environment) => {
     registerElectronObservationCommands(cli, logger);
+    registerElectronFuseCommand(cli, logger);
     registerElectronActiveCommand(cli, logger, environment);
     registerJavaScriptApplicationCommand(cli, logger);
     registerJavaScriptRuntimeReconciliationCommand(cli, logger);
 };
+const registerElectronFuseCommand = (cli, logger) => {
+    const service = createElectronFuseService();
+    cli.command(CLI_COMMANDS.inspectElectronFuses, {
+        description: "Inspect packaged Electron fuse bytes without launching the application",
+        args: z.object({
+            path: z
+                .string()
+                .describe("Local Electron .app, Electron Framework binary, PE executable, or ELF executable"),
+        }),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectElectronFuses, async () => {
+            const result = await service.inspect({ path: absoluteElectronFusePath(args.path) }, { signal });
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        })),
+    });
+};
+/** Anchor relative input without changing which file symlink/.. selects. */
+const absoluteElectronFusePath = (path) => {
+    if (path === "")
+        return path;
+    // Win32 resolves dot components before directory links, including drive-relative paths.
+    if (sep === "\\")
+        return resolve(path);
+    if (isAbsolute(path))
+        return path;
+    const base = process.cwd();
+    return `${base}${base.endsWith(sep) ? "" : sep}${path}`;
+};
 const registerElectronActiveCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureElectronScenario, {
         description: "Run one owned Electron scenario with cancellable actions",
@@ -39,6 +66,7 @@ const registerElectronActiveCommand = (cli, logger, environment) => {
             ]));
             if (!parsed.success)
                 return inputError("capture_electron_scenario", parsed.error.issues, input.value);
+            const { captureElectronScenario } = await import("../application/javascript/ElectronActiveObservationService.js");
             const { createElectronScenarioProvider } = await import("../composition/electronScenario.js");
             const result = await captureElectronScenario(createElectronScenarioProvider(environment), parsed.data, { signal });
             return result.ok ? result.value : cliError(result.error);
@@ -57,6 +85,7 @@ const registerJavaScriptRuntimeReconciliationCommand = (cli, logger) => {
             const input = await parseCliJsonInput(args.inputJson, "reconcile_javascript_runtime");
             if (!input.ok)
                 return input.error;
+            const { reconcileJavaScriptRuntimeEvidence } = await import("../application/javascript/JavaScriptRuntimeReconciliationService.js");
             const result = reconcileJavaScriptRuntimeEvidence(input.value);
             return result.ok ? result.value : cliError(result.error);
         }),
@@ -79,6 +108,7 @@ const registerElectronTargetList = (cli, logger) => {
             });
             if (!parsed.success)
                 return inputError("list_electron_targets");
+            const { listElectronTargets } = await import("../application/javascript/ElectronObservationService.js");
             const result = await listElectronTargets(context.provider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
@@ -102,6 +132,7 @@ const registerElectronPageInspection = (cli, logger) => {
             });
             if (!parsed.success)
                 return inputError("inspect_electron_page");
+            const { inspectElectronPage } = await import("../application/javascript/ElectronObservationService.js");
             const result = await inspectElectronPage(context.provider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
@@ -118,6 +149,17 @@ const registerJavaScriptApplicationCommand = (cli, logger) => {
             input_path: args.path,
             format: options.artifactFormat,
             integrity_policy: options.integrityPolicy,
+            ...(options.maxSemanticNodes === undefined
+                ? {}
+                : { max_semantic_nodes: options.maxSemanticNodes }),
+            ...(options.maxSemanticNodesPerFile === undefined
+                ? {}
+                : {
+                    max_semantic_nodes_per_file: options.maxSemanticNodesPerFile,
+                }),
+            ...(options.sourcePath === undefined
+                ? {}
+                : { source_paths: options.sourcePath }),
             ...(options.maxHeapMb === undefined
                 ? {}
                 : { max_heap_mb: options.maxHeapMb }),

package/dist/cli/evmCommands.js

@@ -1,14 +1,13 @@
 import { z } from "incur";
 import { resolve } from "node:path";
-import { createEvmInterfaceService } from "../composition/evm.js";
-import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { evmInterfaceModule } from "../composition/evm.js";
 import { logCliCommand } from "../cliLogging.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { withCommandCancellation } from "./commandCancellation.js";
 /** Resolve operator paths and preserve explicit encoding through the shared workflow. */
 export const registerEvmCommands = (cli, logger, environment) => {
-    const service = createEvmInterfaceService(environment);
-    cli.command(CLI_COMMANDS.inspectEvmInterface, {
+    const service = evmInterfaceModule.create(environment);
+    cli.command(evmInterfaceModule.cliCommand, {
         description: "Infer interface candidates from explicit local EVM bytecode",
         args: z.object({
             path: z.string().describe("Local bytecode carrier"),
@@ -18,7 +17,7 @@ export const registerEvmCommands = (cli, logger, environment) => {
         }),
         run: ({ args }) => withCommandCancellation(async (signal) => {
             try {
-                return await logCliCommand(logger, CLI_COMMANDS.inspectEvmInterface, async () => {
+                return await logCliCommand(logger, evmInterfaceModule.cliCommand, async () => {
                     const result = await service.inspect({ path: resolve(args.path), encoding: args.encoding }, { signal });
                     return result.ok
                         ? result.value

package/dist/cli/finishAnalysisCommand.js

@@ -0,0 +1,44 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+/** Finish a one-shot CLI operation without discarding its primary result on close failure. */
+export const finishAnalysisCommand = async (run, service, providerId, canonicalOperation, fallbackResource) => {
+    let result;
+    try {
+        result = await run();
+    }
+    catch (cause) {
+        result = {
+            ok: false,
+            error: cause instanceof AnalysisError
+                ? cause
+                : new ProviderAdapterError(providerId, canonicalOperation, { cause }),
+        };
+    }
+    try {
+        await service.close();
+    }
+    catch (cause) {
+        let cleanup;
+        if (cause instanceof AnalysisError)
+            cleanup = cause;
+        else {
+            const observation = cause instanceof ArtifactReaderFailure
+                ? ArtifactReaderFailure.cleanupObservation(cause, fallbackResource ?? `${canonicalOperation} resources`)
+                : {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    resources: [],
+                };
+            cleanup = new ProviderCleanupError(providerId, observation.resources, { reason: observation.reason }, { cause, operation: canonicalOperation });
+        }
+        if (result.ok)
+            cleanup.retainPartialObservation(result.value);
+        return projectAnalysisError(result.ok
+            ? cleanup
+            : analysisErrorWithCleanupFailure(result.error, cleanup, canonicalOperation));
+    }
+    return result.ok ? result.value : projectAnalysisError(result.error);
+};