rea-agents 6.2.0 → 6.4.0

package/dist/cli/browserAdvancedCommands.js

@@ -6,9 +6,10 @@ import { CdpBrowserProvider } from "../browser/CdpBrowserProvider.js";
 import { logCliCommand } from "../cliLogging.js";
 import { AnalysisInputError, } from "../domain/analysisErrorCore.js";
 import { browserCaptureComparisonInputSchema } from "../domain/browserCaptureComparison.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "../domain/webScreenshot.js";
-import { safeParseJson } from "../domain/safeJson.js";
+import { parseCliJsonInput } from "../cliJsonInput.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 /** Register WebMCP, capture-diff, and screenshot CLI equivalents. */
 export const registerAdvancedBrowserCommands = (cli, logger) => {
@@ -52,42 +53,36 @@ const registerCaptureDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebCaptures, {
         description: "Compare two normalized passive captures or recorded browser scenarios",
         args: z.object({
-            beforeJson: z.string().describe("Earlier normalized web capture JSON"),
-            afterJson: z.string().describe("Later normalized web capture JSON"),
+            beforeJson: z
+                .string()
+                .describe("Earlier normalized web capture JSON or JSON file path"),
+            afterJson: z
+                .string()
+                .describe("Later normalized web capture JSON or JSON file path"),
         }),
         options: z.object({
             normalizationJson: z
                 .string()
                 .default('{"rules":[]}')
-                .describe("Recorded literal normalization policy for browser scenarios"),
+                .describe("Recorded literal normalization policy JSON or JSON file path for browser scenarios"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-captures", async () => {
-            const before = safeParseJson(args.beforeJson);
-            const after = safeParseJson(args.afterJson);
-            const normalization = safeParseJson(options.normalizationJson);
-            if (!before.ok)
-                return inputError("compare_web_captures", [
-                    invalidJsonIssue("before"),
-                ]);
-            if (!after.ok)
-                return inputError("compare_web_captures", [
-                    invalidJsonIssue("after"),
-                ]);
-            if (!normalization.ok)
-                return inputError("compare_web_captures", [
-                    invalidJsonIssue("normalization"),
-                ]);
+            const inputs = await parseJsonArguments("compare_web_captures", {
+                before: args.beforeJson,
+                after: args.afterJson,
+                normalization: options.normalizationJson,
+            });
+            if (!inputs.ok)
+                return inputs.error;
+            const { before, after, normalization } = inputs.value;
             const scenarioComparison = browserCaptureComparisonInputSchema.safeParse({
-                before_scenario: before.value,
-                after_scenario: after.value,
-                normalization: normalization.value,
+                before_scenario: before,
+                after_scenario: after,
+                normalization,
             });
             const parsed = scenarioComparison.success
                 ? scenarioComparison
-                : browserCaptureComparisonInputSchema.safeParse({
-                    before: before.value,
-                    after: after.value,
-                });
+                : browserCaptureComparisonInputSchema.safeParse({ before, after });
             if (!parsed.success)
                 return inputError("compare_web_captures");
             const result = await compareWebCaptureEvidence(new CdpBrowserProvider(), parsed.data);
@@ -123,8 +118,12 @@ const registerScreenshotDiff = (cli, logger) => {
     cli.command(CLI_COMMANDS.compareWebScreenshots, {
         description: "Compare two self-verifying PNG artifact JSON values",
         args: z.object({
-            beforeJson: z.string().describe("Earlier screenshot artifact JSON"),
-            afterJson: z.string().describe("Later screenshot artifact JSON"),
+            beforeJson: z
+                .string()
+                .describe("Earlier screenshot artifact JSON or JSON file path"),
+            afterJson: z
+                .string()
+                .describe("Later screenshot artifact JSON or JSON file path"),
         }),
         options: z.object({
             channelThreshold: z
@@ -136,22 +135,52 @@ const registerScreenshotDiff = (cli, logger) => {
                 .describe("Per-channel difference threshold for changed pixels"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "compare-web-screenshots", async () => {
-            const parsed = compareWebScreenshotsInputSchema.safeParse({
-                before: parseJson(args.beforeJson),
-                after: parseJson(args.afterJson),
-                channel_threshold: options.channelThreshold,
+            const operation = "compare_web_screenshots";
+            const inputs = await parseJsonArguments(operation, {
+                before: args.beforeJson,
+                after: args.afterJson,
             });
+            if (!inputs.ok)
+                return inputs.error;
+            const { before, after } = inputs.value;
+            const input = {
+                before,
+                after,
+                channel_threshold: options.channelThreshold,
+            };
+            const parsed = compareWebScreenshotsInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("compare_web_screenshots");
+                return browserCliError(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, input)));
             const result = await compareWebScreenshotEvidence(new CdpBrowserProvider(), parsed.data);
             return result.ok ? result.value : browserCliError(result.error);
         }),
     });
 };
-const parseJson = (value) => {
-    const parsed = safeParseJson(value);
-    return parsed.ok ? parsed.value : undefined;
+/**
+ * Parse each named inline JSON argument or local JSON file, like other
+ * JSON-input commands. Screenshot artifacts and scenario captures embed PNG
+ * bytes that can exceed the host's command-line length limit.
+ */
+const parseJsonArguments = async (operation, fields) => {
+    const values = {};
+    for (const [field, value] of Object.entries(fields)) {
+        const parsed = await parseCliJsonInput(value, operation);
+        if (!parsed.ok)
+            return isFileInputFailure(parsed.error)
+                ? parsed
+                : {
+                    ok: false,
+                    error: inputError(operation, [invalidJsonIssue(field)]),
+                };
+        values[field] = parsed.value;
+    }
+    return { ok: true, value: values };
 };
+/** File read and decode failures name the selected path; inline JSON does not. */
+const isFileInputFailure = (error) => typeof error === "object" &&
+    error !== null &&
+    !Array.isArray(error) &&
+    "input_path" in error;
 const invalidJsonIssue = (field) => ({
     path: [field],
     reason: "invalid_format",

package/dist/cli/coreAnalysisCommands.js

@@ -1,7 +1,7 @@
 import { registerCoreBinaryCommands } from "./coreBinaryCommands.js";
 import { registerCoreNativeCommands } from "./coreNativeCommands.js";
 /** Register core binary and native deep-analysis CLI commands. */
-export const registerCoreAnalysisCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
-    registerCoreBinaryCommands(cli, logger, runDirectAnalysis, resultOutput);
+export const registerCoreAnalysisCommands = (cli, logger, runDirectAnalysis) => {
+    registerCoreBinaryCommands(cli, logger, runDirectAnalysis);
     registerCoreNativeCommands(cli, logger, runDirectAnalysis);
 };

package/dist/cli/coreBinaryCommands.js

@@ -7,9 +7,10 @@ import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 import { withCommandCancellation } from "./commandCancellation.js";
+import { javascriptApplicationOptions } from "../cliObservationOptions.js";
 /** Register provider-neutral binary overview and procedure CLI commands. */
-export const registerCoreBinaryCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
-    registerOverviewCommands(cli, logger, runDirectAnalysis, resultOutput);
+export const registerCoreBinaryCommands = (cli, logger, runDirectAnalysis) => {
+    registerOverviewCommands(cli, logger, runDirectAnalysis);
     registerDecompileCommand(cli, logger, runDirectAnalysis);
     registerFunctionCommand(cli, logger, runDirectAnalysis);
     registerInstructionsCommand(cli, logger, runDirectAnalysis);
@@ -17,7 +18,7 @@ export const registerCoreBinaryCommands = (cli, logger, runDirectAnalysis, resul
     registerXrefsCommand(cli, logger, runDirectAnalysis);
     registerTraceCommand(cli, logger, runDirectAnalysis);
 };
-const registerOverviewCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
+const registerOverviewCommands = (cli, logger, runDirectAnalysis) => {
     const overviewOptions = z.object({
         snapshot: z
             .string()
@@ -32,16 +33,18 @@ const registerOverviewCommands = (cli, logger, runDirectAnalysis, resultOutput)
         args: z.object({
             path: z.string().describe("App, program, or analysis database path"),
         }),
-        options: overviewOptions,
-        run: async ({ args, options, format }) => {
-            const output = resultOutput === undefined
-                ? undefined
-                : { output: resultOutput, command: CLI_COMMANDS.analyze, format };
+        options: overviewOptions.extend({
+            integrityPolicy: javascriptApplicationOptions.shape.integrityPolicy,
+        }),
+        run: async ({ args, options }) => {
             // Route JavaScript targets exactly like analyze-javascript-application,
             // including typed cancellation; cancellation wraps logging so its exit
             // code is not replaced by the logged failure status.
             if (await routesToJavaScriptAnalysis(args.path, options))
-                return withCommandCancellation((signal) => logCliCommand(logger, "analyze", () => runCliJavaScriptApplicationAnalysis({ input_path: resolve(args.path) }, output, signal)));
+                return withCommandCancellation((signal) => logCliCommand(logger, "analyze", () => runCliJavaScriptApplicationAnalysis({
+                    input_path: resolve(args.path),
+                    integrity_policy: options.integrityPolicy,
+                }, signal)));
             return logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"])));
         },
     });
@@ -156,9 +159,6 @@ const registerTraceCommand = (cli, logger, runDirectAnalysis) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        alias: {
-            caseSensitive: "case-sensitive",
-        },
         run: ({ args, options }) => logCliCommand(logger, "trace", () => runDirectAnalysis(args.path, "trace_feature", {
             query: resolveCliAnalysisSelector(args.query, options.query, "query", "trace_feature"),
             case_sensitive: options.caseSensitive,
@@ -262,7 +262,6 @@ const registerSearchCommand = (cli, logger, runDirectAnalysis) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        alias: { caseSensitive: "case-sensitive" },
         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"
                 ? "search_strings"

package/dist/cli/coreNativeCommands.js

@@ -104,13 +104,6 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        alias: {
-            maxDepth: "max-depth",
-            maxFunctions: "max-functions",
-            maxCallSites: "max-call-sites",
-            maxNodes: "max-nodes",
-            maxEdges: "max-edges",
-        },
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.traceNativeValues, () => runDirectAnalysis(args.path, "trace_native_values", {
             procedure: args.procedure,
             max_depth: options.maxDepth,
@@ -129,7 +122,7 @@ export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
         }),
         options: z.object({
             type: z.string().optional().describe("Exact database type category path"),
-            address: z.string().describe("Exact native address").optional(),
+            address: z.string().optional().describe("Exact native address"),
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
@@ -185,7 +178,6 @@ const registerNativeDispatchMetadataCommand = (cli, logger, runDirectAnalysis) =
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        alias: { maxRecords: "max-records" },
         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"]))),
     });
 };
@@ -224,11 +216,6 @@ const registerNativeUiActionCommand = (cli, logger, runDirectAnalysis) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        alias: {
-            maxDepth: "max-depth",
-            maxNodes: "max-nodes",
-            maxEdges: "max-edges",
-        },
         run: async ({ args, options }) => logCliCommand(logger, "trace-native-ui-action", () => runDirectAnalysis(args.path, "trace_native_ui_action", {
             action: args.action,
             max_depth: options.maxDepth,

package/dist/cli/electronCommands.js

@@ -14,10 +14,10 @@ import { electronPageInspectionOptions, javascriptApplicationOptions, } from "..
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 import { withCommandCancellation } from "./commandCancellation.js";
 /** Register CLI equivalents of the Electron MCP tools. */
-export const registerElectronCommands = (cli, logger, environment, resultOutput) => {
+export const registerElectronCommands = (cli, logger, environment) => {
     registerElectronObservationCommands(cli, logger);
     registerElectronActiveCommand(cli, logger, environment);
-    registerJavaScriptApplicationCommand(cli, logger, resultOutput);
+    registerJavaScriptApplicationCommand(cli, logger);
     registerJavaScriptRuntimeReconciliationCommand(cli, logger);
 };
 const registerElectronActiveCommand = (cli, logger, environment) => {
@@ -107,20 +107,24 @@ const registerElectronPageInspection = (cli, logger) => {
         }),
     });
 };
-const registerJavaScriptApplicationCommand = (cli, logger, resultOutput) => {
+const registerJavaScriptApplicationCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.analyzeJavaScriptApplication, {
         description: "Statically reconstruct a local JavaScript/Electron application",
         args: z.object({
             path: z.string().describe("ASAR or extracted application path"),
         }),
         options: javascriptApplicationOptions,
-        run: ({ args, options, format }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, () => runCliJavaScriptApplicationAnalysis({ input_path: args.path, format: options.artifactFormat }, resultOutput === undefined
-            ? undefined
-            : {
-                output: resultOutput,
-                command: CLI_COMMANDS.analyzeJavaScriptApplication,
-                format,
-            }, signal))),
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, () => runCliJavaScriptApplicationAnalysis({
+            input_path: args.path,
+            format: options.artifactFormat,
+            integrity_policy: options.integrityPolicy,
+            ...(options.maxHeapMb === undefined
+                ? {}
+                : { max_heap_mb: options.maxHeapMb }),
+            ...(options.analysisTimeoutMs === undefined
+                ? {}
+                : { analysis_timeout_ms: options.analysisTimeoutMs }),
+        }, signal))),
     });
 };
 const electronObservationContext = async () => {

package/dist/cli/evmCommands.js

@@ -16,9 +16,18 @@ export const registerEvmCommands = (cli, logger, environment) => {
                 .enum(["raw", "hex"])
                 .describe("Selected carrier representation"),
         }),
-        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectEvmInterface, async () => {
-            const result = await service.inspect({ path: resolve(args.path), encoding: args.encoding }, { signal });
-            return result.ok ? result.value : projectAnalysisError(result.error);
-        })),
+        run: ({ args }) => withCommandCancellation(async (signal) => {
+            try {
+                return await logCliCommand(logger, CLI_COMMANDS.inspectEvmInterface, async () => {
+                    const result = await service.inspect({ path: resolve(args.path), encoding: args.encoding }, { signal });
+                    return result.ok
+                        ? result.value
+                        : projectAnalysisError(result.error);
+                });
+            }
+            finally {
+                await service.close();
+            }
+        }),
     });
 };

package/dist/cli/firmwareCommands.js

@@ -10,8 +10,13 @@ import { withCommandCancellation } from "./commandCancellation.js";
 export const registerFirmwareCommands = (cli, logger, environment) => {
     const service = new FirmwareAnalysisService(createFirmwareAnalysisProvider(environment));
     const execute = (name, operation, input) => withCommandCancellation((signal) => logCliCommand(logger, name, async () => {
-        const result = await service.execute(operation, input, { signal });
-        return result.ok ? result.value : projectAnalysisError(result.error);
+        try {
+            const result = await service.execute(operation, input, { signal });
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        }
+        finally {
+            await service.close();
+        }
     }));
     const path = z.string().describe("Local firmware path; never executed");
     cli.command(CLI_COMMANDS.inspectFirmwareRegions, {

package/dist/cli/javascriptApplicationAnalysis.js

@@ -1,26 +1,32 @@
 import { analyzeJavaScriptApplication } from "../application/javascript/JavaScriptApplicationService.js";
+import { JAVASCRIPT_APPLICATION_PROVIDER } from "../application/InvestigationProviders.js";
 import { createProgressReporter } from "../application/ProgressReporter.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 /** Execute the shared one-shot CLI boundary for static JavaScript analysis. */
-export const runCliJavaScriptApplicationAnalysis = async (input, output, signal) => {
-    const started = performance.now();
+export const runCliJavaScriptApplicationAnalysis = async (input, signal) => {
     const progress = createProgressReporter(async (update) => {
         process.stderr.write(`${JSON.stringify({ rea_progress: update })}\n`);
     }, { minimumIntervalMs: 0 });
-    const result = await analyzeJavaScriptApplication(input, {
+    const resources = new ArtifactResourceScope();
+    const result = await analyzeJavaScriptApplication(input, resources, {
         progress,
         ...(signal === undefined ? {} : { signal }),
     });
-    const value = result.ok ? result.value : cliError(result.error);
-    if (output !== undefined &&
-        (await output.output.write(value, {
-            command: output.command,
-            format: output.format,
-            duration: `${Math.round(performance.now() - started)}ms`,
-        })))
-        // Keep failures visible to command logging after the stream has handled stdout.
-        return result.ok ? undefined : value;
-    return value;
+    try {
+        await resources.close();
+    }
+    catch (cause) {
+        const cleanup = ArtifactReaderFailure.cleanupObservation(cause, "JavaScript application resources");
+        const failure = new ProviderCleanupError(JAVASCRIPT_APPLICATION_PROVIDER.id, cleanup.resources, { reason: cleanup.reason }, { cause, operation: "analyze_javascript_application" });
+        return cliError(result.ok
+            ? failure
+            : analysisErrorWithCleanupFailure(result.error, failure, "analyze_javascript_application"));
+    }
+    return result.ok ? result.value : cliError(result.error);
 };
 const cliError = (error) => ({
     error: "JavaScript application analysis failed",

package/dist/cli/javascriptRecoveryCommands.js

@@ -26,20 +26,27 @@ export const registerJavaScriptRecoveryCommands = (cli, logger, environment) =>
                 .optional()
                 .describe("Upstream syntax recovery level; runtime equivalence remains unknown"),
         }),
-        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.recoverJavaScriptSources, async () => {
-            const result = await service.recover({
-                path: args.path,
-                output_directory: args.outputDirectory,
-                ...(options.extractionMode === undefined
-                    ? {}
-                    : { extraction_mode: options.extractionMode }),
-                ...(options.rewriteLevel === undefined
-                    ? {}
-                    : { rewrite_level: options.rewriteLevel }),
-            }, { signal });
-            return result.ok
-                ? result.value
-                : projectAnalysisError(result.error);
-        })),
+        run: ({ args, options }) => withCommandCancellation(async (signal) => {
+            try {
+                return await logCliCommand(logger, CLI_COMMANDS.recoverJavaScriptSources, async () => {
+                    const result = await service.recover({
+                        path: args.path,
+                        output_directory: args.outputDirectory,
+                        ...(options.extractionMode === undefined
+                            ? {}
+                            : { extraction_mode: options.extractionMode }),
+                        ...(options.rewriteLevel === undefined
+                            ? {}
+                            : { rewrite_level: options.rewriteLevel }),
+                    }, { signal });
+                    return result.ok
+                        ? result.value
+                        : projectAnalysisError(result.error);
+                });
+            }
+            finally {
+                await service.close();
+            }
+        }),
     });
 };

package/dist/cli/jebCommands.js

@@ -0,0 +1,99 @@
+import { z } from "incur";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { JebAnalysisService } from "../application/jeb/JebAnalysisService.js";
+import { createJebAnalysisProvider } from "../composition/jeb.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Expose the same explicit JEB requests through one-shot CLI commands. */
+export const registerJebCommands = (cli, logger, environment, provider = createJebAnalysisProvider(environment)) => {
+    const service = new JebAnalysisService(provider);
+    const execute = (name, operation, input) => withCommandCancellation((signal) => logCliCommand(logger, name, async () => {
+        const result = await service.execute(operation, input, { signal });
+        try {
+            await provider.close();
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return projectAnalysisError(cause);
+            throw cause;
+        }
+        return result.ok ? result.value : projectAnalysisError(result.error);
+    }));
+    cli.command(CLI_COMMANDS.inspectJebClient, {
+        description: "Inspect the running JEB MCP client without opening a target",
+        args: z.object({}),
+        run: () => execute(CLI_COMMANDS.inspectJebClient, "inspect_jeb_client", {}),
+    });
+    cli.command(CLI_COMMANDS.openJebProject, {
+        description: "Open or create a JEB project from an artifact or .jdb2 database",
+        args: z.object({
+            path: z
+                .string()
+                .describe("Artifact or .jdb2 path resolved by the JEB engine host"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.openJebProject, "open_jeb_project", args),
+    });
+    cli.command(CLI_COMMANDS.listJebUnits, {
+        description: "List JEB project units by path and type with optional filter",
+        args: z.object({}),
+        options: z.object({
+            filter: z
+                .string()
+                .optional()
+                .describe("Wildcard filter matched against unit paths"),
+            "parent-unit-path": z
+                .string()
+                .optional()
+                .describe("Restrict results to descendants of this unit path"),
+            index: z
+                .number()
+                .int()
+                .nonnegative()
+                .default(0)
+                .describe("Zero-based index of the first result to return"),
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(100)
+                .describe("Maximum results; the engine caps unit pages at 100"),
+        }),
+        run: ({ options }) => execute(CLI_COMMANDS.listJebUnits, "list_jeb_units", {
+            index: options.index,
+            count: options.count,
+            ...(options.filter === undefined ? {} : { filter: options.filter }),
+            ...(options["parent-unit-path"] === undefined
+                ? {}
+                : { parent_unit_path: options["parent-unit-path"] }),
+        }),
+    });
+    cli.command(CLI_COMMANDS.decompileJebItem, {
+        description: "Decompile one JEB type or method to engine pseudo-code",
+        args: z.object({
+            "item-address": z
+                .string()
+                .min(1)
+                .describe("Type or method address within the unit"),
+            "item-kind": z
+                .enum(["type", "method"])
+                .describe("Kind of item to decompile"),
+        }),
+        options: z.object({
+            "unit-path": z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Target code unit; the engine's first code unit when omitted"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.decompileJebItem, "decompile_jeb_item", {
+            item_address: args["item-address"],
+            item_kind: args["item-kind"],
+            ...(options["unit-path"] === undefined
+                ? {}
+                : { unit_path: options["unit-path"] }),
+        }),
+    });
+};

package/dist/cli/jsonOutput.js

@@ -1,9 +1,16 @@
 import { bufferedJsonParts, jsonParts } from "../domain/jsonSerialization.js";
-/** Write ordinary JSON without constructing a document-sized string. */
+/**
+ * Write ordinary JSON without constructing a document-sized string.
+ *
+ * `json` is indented for a terminal reader. Piped or redirected output, which
+ * agents and scripts consume, is compact: indentation adds no information and
+ * measured 16-45% more model tokens on real results. The value is identical.
+ */
 export const writeJsonOutput = async (value, destination, format = "json") => {
-    for (const part of bufferedJsonParts(documentParts(value, format)))
+    for (const part of bufferedJsonParts(jsonOutputParts(value, format, isTerminal(destination))))
         await writePart(destination, part);
 };
+const isTerminal = (destination) => "isTTY" in destination && destination.isTTY === true;
 const writePart = (destination, part) => new Promise((resolve, reject) => {
     const onError = (cause) => reject(cause);
     destination.once("error", onError);
@@ -25,7 +32,8 @@ const writePart = (destination, part) => new Promise((resolve, reject) => {
         reject(cause);
     }
 });
-function* documentParts(value, format) {
+/** The exact formatted document, including its final newline. */
+export function* jsonOutputParts(value, format, pretty = true) {
     if (format === "jsonl" && Array.isArray(value)) {
         for (const item of value) {
             yield* jsonParts(item);
@@ -33,6 +41,6 @@ function* documentParts(value, format) {
         }
         return;
     }
-    yield* jsonParts(value, format === "json");
+    yield* jsonParts(value, pretty && format === "json");
     yield "\n";
 }

package/dist/cli/referenceSourceImportStatus.js

@@ -9,6 +9,13 @@ const referenceSourceImportFailureSchema = z.strictObject({
         "execution_failure",
     ]),
     message: z.string().min(1),
+    cleanup: z
+        .strictObject({
+        reason: z.string().min(1),
+        resources: z.array(z.string().min(1)),
+    })
+        .optional(),
+    partial: z.unknown().optional(),
 });
 /** Identify the historical-source import command's failed operation outputs. */
 export const isReferenceSourceImportCliFailure = (value) => referenceSourceImportFailureSchema.safeParse(value).success ||