rea-agents 4.1.0 → 6.0.0

package/dist/cli/javascriptApplicationAnalysis.js

@@ -1,9 +1,22 @@
-import { analyzeJavaScriptApplication } from "../application/JavaScriptApplicationService.js";
+import { analyzeJavaScriptApplication } from "../application/javascript/JavaScriptApplicationService.js";
+import { createProgressReporter } from "../application/ProgressReporter.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 /** Execute the shared one-shot CLI boundary for static JavaScript analysis. */
-export const runCliJavaScriptApplicationAnalysis = async (input) => {
-    const result = await analyzeJavaScriptApplication(input);
-    return result.ok ? result.value : cliError(result.error);
+export const runCliJavaScriptApplicationAnalysis = async (input, output) => {
+    const started = performance.now();
+    const progress = createProgressReporter(async (update) => {
+        process.stderr.write(`${JSON.stringify({ rea_progress: update })}\n`);
+    }, { minimumIntervalMs: 0 });
+    const result = await analyzeJavaScriptApplication(input, { progress });
+    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`,
+        })))
+        return undefined;
+    return value;
 };
 const cliError = (error) => ({
     error: "JavaScript application analysis failed",

package/dist/cli/javascriptRecoveryCommands.js

@@ -0,0 +1,45 @@
+import { z } from "incur";
+import { JavaScriptRecoveryService } from "../application/javascript/JavaScriptRecoveryService.js";
+import { createJavaScriptRecoveryProvider } from "../composition/javascriptRecovery.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Share source recovery with MCP while keeping CLI spelling at this boundary. */
+export const registerJavaScriptRecoveryCommands = (cli, logger, environment) => {
+    const service = new JavaScriptRecoveryService(createJavaScriptRecoveryProvider(environment));
+    cli.command(CLI_COMMANDS.recoverJavaScriptSources, {
+        description: "Recover readable JavaScript modules with source provenance and verified files",
+        args: z.object({
+            path: z
+                .string()
+                .describe("Absolute UTF-8 JavaScript input; never executed"),
+            outputDirectory: z.string().describe("Absolute absent output directory"),
+        }),
+        options: z.object({
+            extractionMode: z
+                .enum(["structural", "heuristic", "inspection"])
+                .optional()
+                .describe("Structural boundaries, heuristic fallback, or inspection-only regions"),
+            rewriteLevel: z
+                .enum(["minimal", "standard", "aggressive"])
+                .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);
+        })),
+    });
+};

package/dist/cli/jsonOutput.js

@@ -0,0 +1,133 @@
+/** Write ordinary JSON without constructing a document-sized string. */
+export const writeJsonOutput = async (value, destination, format = "json") => {
+    for (const part of bufferedParts(documentParts(value, format)))
+        await writePart(destination, part);
+};
+const writePart = (destination, part) => new Promise((resolve, reject) => {
+    const onError = (cause) => reject(cause);
+    destination.once("error", onError);
+    try {
+        destination.write(part, (cause) => {
+            if (cause) {
+                // A Writable can emit its error after invoking the write callback.
+                setImmediate(() => destination.off("error", onError));
+                reject(cause);
+            }
+            else {
+                destination.off("error", onError);
+                resolve();
+            }
+        });
+    }
+    catch (cause) {
+        destination.off("error", onError);
+        reject(cause);
+    }
+});
+function* documentParts(value, format) {
+    if (format === "jsonl" && Array.isArray(value)) {
+        for (const item of value) {
+            yield* encodeValue(item, false, 0, new Set());
+            yield "\n";
+        }
+        return;
+    }
+    yield* encodeValue(value, format === "json", 0, new Set());
+    yield "\n";
+}
+function* bufferedParts(parts) {
+    let buffer = "";
+    for (const part of parts) {
+        if (buffer.length + part.length > 64 * 1024 && buffer !== "") {
+            yield buffer;
+            buffer = "";
+        }
+        buffer += part;
+    }
+    if (buffer !== "")
+        yield buffer;
+}
+function* encodeString(value) {
+    if (value.length <= 8192) {
+        yield JSON.stringify(value);
+        return;
+    }
+    yield '"';
+    for (let start = 0; start < value.length;) {
+        let end = Math.min(start + 8192, value.length);
+        const last = value.charCodeAt(end - 1);
+        const next = value.charCodeAt(end);
+        // Keep a surrogate pair in the same JSON.stringify and UTF-8 write.
+        if (end < value.length &&
+            last >= 0xd800 &&
+            last <= 0xdbff &&
+            next >= 0xdc00 &&
+            next <= 0xdfff)
+            end -= 1;
+        yield JSON.stringify(value.slice(start, end)).slice(1, -1);
+        start = end;
+    }
+    yield '"';
+}
+function* encodeValue(value, pretty, depth, ancestors) {
+    if (typeof value === "string") {
+        yield* encodeString(value);
+        return;
+    }
+    if (value === null || typeof value === "boolean") {
+        yield value === null ? "null" : String(value);
+        return;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        yield String(value);
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        throw new TypeError("CLI JSON output requires ordinary JSON values");
+    if (ancestors.has(value))
+        throw new TypeError("CLI JSON output contains a circular reference");
+    if (!Array.isArray(value) &&
+        Object.prototype.toString.call(value) !== "[object Object]")
+        throw new TypeError("CLI JSON output requires ordinary JSON objects");
+    ancestors.add(value);
+    try {
+        const array = Array.isArray(value);
+        const keys = array
+            ? undefined
+            : Object.keys(value).filter((key) => {
+                const item = Reflect.get(value, key);
+                // Incur's filter can select inherited methods. Match native JSON's
+                // omission of fields that have no JSON representation.
+                return (item !== undefined &&
+                    typeof item !== "function" &&
+                    typeof item !== "symbol");
+            });
+        const count = array ? value.length : (keys?.length ?? 0);
+        yield array ? "[" : "{";
+        for (let index = 0; index < count; index += 1) {
+            if (index > 0)
+                yield ",";
+            if (pretty)
+                yield `\n${"  ".repeat(depth + 1)}`;
+            let item;
+            if (array) {
+                item = value[index];
+            }
+            else {
+                const key = keys?.[index];
+                if (key === undefined)
+                    throw new TypeError("CLI JSON object changed during serialization");
+                yield* encodeString(key);
+                yield pretty ? ": " : ":";
+                item = Reflect.get(value, key);
+            }
+            yield* encodeValue(item, pretty, depth + 1, ancestors);
+        }
+        if (pretty && count > 0)
+            yield `\n${"  ".repeat(depth)}`;
+        yield array ? "]" : "}";
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}

package/dist/cli/managedCommands.js

@@ -1,8 +1,8 @@
 import { z } from "incur";
-import { compareManagedMemberPaths } from "../application/ManagedMemberComparisonService.js";
-import { verifyManagedNativeBoundariesEvidence } from "../application/ManagedNativeVerificationService.js";
-import { importManagedReconstructionEvidence } from "../application/ManagedReconstructionService.js";
-import { runProviderAnalysis } from "../application/DirectAnalysis.js";
+import { compareManagedMemberPaths } from "../application/managed/ManagedMemberComparisonService.js";
+import { verifyManagedNativeBoundariesEvidence } from "../application/managed/ManagedNativeVerificationService.js";
+import { importManagedReconstructionEvidence } from "../application/managed/ManagedReconstructionService.js";
+import { runProviderAnalysis } from "../composition/directAnalysis.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";

package/dist/cli/managedProjectGraphCommand.js

@@ -1,5 +1,5 @@
 import { z } from "incur";
-import { projectManagedApplicationGraphEvidence } from "../application/ManagedApplicationGraphService.js";
+import { projectManagedApplicationGraphEvidence } from "../application/managed/ManagedApplicationGraphService.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { logCliCommand } from "../cliLogging.js";

package/dist/cli/nativeCallCommands.js

@@ -0,0 +1,35 @@
+import { z } from "incur";
+import { runProviderAnalysis } from "../composition/directAnalysis.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { parseCliJsonInput } from "../cliJsonInput.js";
+import { logCliCommand } from "../cliLogging.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { nativeCallObservationInputSchema } from "../domain/native/nativeCallObservation.js";
+const OPERATION = "observe_native_calls";
+/** `observe-native-calls <path> <input-json>`: the MCP input object as JSON. */
+export const registerNativeCallCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.observeNativeCalls, {
+        description: "Launch a Mach-O under LLDB and record entries into selected functions or Objective-C methods",
+        args: z.object({
+            path: z.string().describe("Mach-O or app path"),
+            inputJson: z
+                .string()
+                .describe("Inline JSON or a JSON file path: breakpoints, arguments, environment, duration_ms, max_events, argument_registers, backtrace_frames"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.observeNativeCalls, async () => {
+            const input = await parseCliJsonInput(args.inputJson, OPERATION);
+            if (!input.ok)
+                return input.error;
+            const parsed = nativeCallObservationInputSchema.safeParse(input.value);
+            if (!parsed.success)
+                return {
+                    error: "Analysis failed",
+                    ...projectAnalysisError(new AnalysisInputError(OPERATION, undefined, projectInputIssues(parsed.error.issues, input.value))),
+                };
+            return runProviderAnalysis(args.path, OPERATION, z.record(z.string(), jsonValueSchema).parse(parsed.data), logger);
+        }),
+    });
+};

package/dist/cli/processCommands.js

@@ -1,5 +1,5 @@
 import { Cli, z } from "incur";
-import { captureProcessScenarioFile, compareProcessEvidenceFiles, isProcessCliFailure, } from "../application/ProcessCli.js";
+import { captureProcessScenarioFile, compareProcessEvidenceFiles, isProcessCliFailure, } from "../application/process/ProcessCli.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 /** Register direct process capture and comparison commands. */

package/dist/cli/referenceSourceImportStatus.js

@@ -2,7 +2,12 @@ import { z } from "zod";
 import { isCliOperationFailure } from "../cliLogging.js";
 const referenceSourceImportFailureSchema = z.strictObject({
     error: z.literal("Import failed"),
-    category: z.enum(["cancelled", "invalid_input", "execution_failure"]),
+    category: z.enum([
+        "cancelled",
+        "invalid_input",
+        "unsupported_host",
+        "execution_failure",
+    ]),
     message: z.string().min(1),
 });
 /** Identify the historical-source import command's failed operation outputs. */

package/dist/cli/streamedJsonOutput.js

@@ -0,0 +1,56 @@
+import {} from "node:stream";
+import { Filter } from "incur";
+import { parseCliOutputArguments } from "../cliOutput.js";
+import { writeJsonOutput } from "./jsonOutput.js";
+/** 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;
+    return {
+        get handled() {
+            return handled;
+        },
+        get failed() {
+            return failed;
+        },
+        async write(value, metadata) {
+            if (metadata.format !== format)
+                return false;
+            const filtered = options.filterOutput
+                ? Filter.apply(value, Filter.parse(options.filterOutput))
+                : value;
+            const meta = {
+                command: metadata.command,
+                duration: metadata.duration,
+            };
+            const document = options.fullOutput
+                ? filtered === undefined
+                    ? { ok: true, meta }
+                    : { ok: true, data: filtered, meta }
+                : filtered === undefined ||
+                    filtered === null ||
+                    typeof filtered === "function" ||
+                    typeof filtered === "symbol"
+                    ? {}
+                    : filtered;
+            // Once writing starts, a failed destination must not receive a second
+            // document from Incur's error formatter.
+            handled = true;
+            try {
+                await writeJsonOutput(document, destination, format);
+            }
+            catch (cause) {
+                failed = true;
+                throw cause;
+            }
+            return true;
+        },
+    };
+};

package/dist/cli/utilityCommands.js

@@ -1,17 +1,23 @@
 import { z } from "incur";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-import { runCapabilityStatus, runProviderAnalysis, runProviderStatus, } from "../application/DirectAnalysis.js";
+import { runCapabilityStatus, runProviderAnalysis, runProviderStatus, } from "../composition/directAnalysis.js";
 import { importReferenceSource } from "../application/ReferenceSourceImport.js";
 import { projectReferenceSourceImportError } from "../application/ReferenceSourceImportTypes.js";
 import { parseConfig } from "../config.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { safeParseJson } from "../domain/safeJson.js";
+import { nativeUiScenarioInputSchema } from "../domain/native/nativeUiObservation.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { swiftSymbolsSchema } from "../contracts/native/nativeToolContracts.js";
 import { isReferenceSourceImportCliFailure } from "./referenceSourceImportStatus.js";
+import { registerNativeCallCommands } from "./nativeCallCommands.js";
 export const registerUtilityCommands = (cli, logger, environment = process.env) => {
     registerCapabilityCommands(cli, logger);
     registerNativeCommands(cli, logger);
+    registerNativeCallCommands(cli, logger);
     for (const [command, operation] of [
         [CLI_COMMANDS.observeNativeUi, "observe_native_ui"],
         [CLI_COMMANDS.captureNativeUiScenario, "capture_native_ui_scenario"],
@@ -52,24 +58,45 @@ export const registerUtilityCommands = (cli, logger, environment = process.env)
                 windowId: "window-id",
                 maxNodes: "max-nodes",
             },
-            run: ({ args, options }) => logCliCommand(logger, command, () => runProviderAnalysis(args.path, operation, {
-                pid: options.pid,
-                window_id: options.windowId,
-                screenshot: options.screenshot,
-                accessibility: options.accessibility,
-                max_nodes: options.maxNodes,
-                ...(operation === "capture_native_ui_scenario"
-                    ? {
-                        steps: options.steps === undefined
-                            ? []
-                            : jsonValueSchema.parse(JSON.parse(options.steps)),
-                    }
-                    : {}),
-            }, logger)),
+            run: ({ args, options }) => logCliCommand(logger, command, async () => {
+                const parameters = {
+                    pid: options.pid,
+                    window_id: options.windowId,
+                    screenshot: options.screenshot,
+                    accessibility: options.accessibility,
+                    max_nodes: options.maxNodes,
+                };
+                if (operation === "capture_native_ui_scenario") {
+                    const decoded = options.steps === undefined
+                        ? { ok: true, value: undefined }
+                        : safeParseJson(options.steps);
+                    if (!decoded.ok)
+                        return invalidNativeUiScenarioInput(operation, [
+                            { path: ["steps"], reason: "invalid_format", expected: "JSON" },
+                        ]);
+                    const parsed = nativeUiScenarioInputSchema.safeParse({
+                        ...parameters,
+                        steps: decoded.value,
+                    });
+                    if (!parsed.success)
+                        return invalidNativeUiScenarioInput(operation, projectInputIssues(parsed.error.issues, {
+                            ...parameters,
+                            ...(options.steps === undefined
+                                ? {}
+                                : { steps: decoded.value }),
+                        }));
+                    return runProviderAnalysis(args.path, operation, parsed.data, logger);
+                }
+                return runProviderAnalysis(args.path, operation, parameters, logger);
+            }),
         });
     }
     registerReferenceSourceCommand(cli, logger, environment);
 };
+const invalidNativeUiScenarioInput = (operation, issues) => ({
+    error: "Application workflow failed",
+    ...projectAnalysisError(new AnalysisInputError(operation, undefined, issues)),
+});
 const registerCapabilityCommands = (cli, logger) => {
     for (const command of [
         CLI_COMMANDS.capabilities,
@@ -103,20 +130,19 @@ const registerNativeCommands = (cli, logger) => {
         options: z.object({
             relativePath: z
                 .string()
-                .default("Contents/Info.plist")
-                .describe("Plist path relative to the app root"),
+                .optional()
+                .describe("Plist path relative to the app root (default: Contents/Info.plist)"),
         }),
         alias: { relativePath: "relative-path" },
-        run: ({ args, options }) => logCliCommand(logger, "inspect-plist", () => runProviderAnalysis(args.path, "inspect_plist", { relative_path: options.relativePath }, logger)),
+        run: ({ args, options }) => logCliCommand(logger, "inspect-plist", () => runProviderAnalysis(args.path, "inspect_plist", options.relativePath === undefined
+            ? {}
+            : { path: options.relativePath }, logger)),
     });
     cli.command(CLI_COMMANDS.demangleSwift, {
         description: "Demangle Swift symbols without Hopper",
         args: z.object({
             path: z.string().describe("Artifact path used for evidence identity"),
-            symbols: z
-                .array(z.string().min(1))
-                .min(1)
-                .describe("Swift mangled symbols to demangle"),
+            symbols: swiftSymbolsSchema.describe("Swift mangled symbols to demangle"),
         }),
         run: ({ args }) => logCliCommand(logger, "demangle-swift", () => runProviderAnalysis(args.path, "demangle_swift", { symbols: args.symbols }, logger)),
     });

package/dist/cli/webModuleCommands.js

@@ -0,0 +1,56 @@
+import { z } from "incur";
+import { createWebModuleTraceService } from "../composition/webModules.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 selected-context module trace through the CLI. */
+export const registerWebModuleCommands = (cli, logger, environment) => {
+    const service = createWebModuleTraceService(environment);
+    cli.command(CLI_COMMANDS.traceWebModuleImports, {
+        description: "Trace one captured script's native imports to URLs and captured source candidates",
+        args: z.object({
+            manifestPath: z
+                .string()
+                .describe("Absolute export_web_scripts manifest path"),
+            scriptIndex: z.coerce
+                .number()
+                .int()
+                .min(0)
+                .describe("Zero-based manifest script index"),
+        }),
+        options: z.object({
+            importerUrl: z
+                .string()
+                .optional()
+                .describe("Explicit HTTP(S) importer URL"),
+            importMapPath: z
+                .string()
+                .optional()
+                .describe("Absolute local import-map JSON"),
+            importMapBaseUrl: z
+                .string()
+                .optional()
+                .describe("HTTP(S) import-map base URL"),
+        }),
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.traceWebModuleImports, async () => {
+            const result = await service.trace({
+                manifest_path: args.manifestPath,
+                script_index: args.scriptIndex,
+                ...(options.importerUrl === undefined
+                    ? {}
+                    : { importer_url: options.importerUrl }),
+                ...(options.importMapPath === undefined &&
+                    options.importMapBaseUrl === undefined
+                    ? {}
+                    : {
+                        import_map: {
+                            path: options.importMapPath,
+                            base_url: options.importMapBaseUrl,
+                        },
+                    }),
+            }, { signal });
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        })),
+    });
+};

package/dist/cli/webNetworkCaptureCommands.js

@@ -0,0 +1,40 @@
+import { z } from "incur";
+import { createWebNetworkCaptureService } from "../composition/webNetworkCaptures.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Expose offline historical capture inspection with the same selection contract as MCP. */
+export const registerWebNetworkCaptureCommands = (cli, logger, environment) => {
+    const service = createWebNetworkCaptureService(environment);
+    cli.command(CLI_COMMANDS.inspectWebNetworkCapture, {
+        description: "Inspect retained HAR or native mitmproxy records without fetching recorded URLs",
+        args: z.object({
+            capturePath: z.string().describe("Absolute local capture path"),
+            format: z.enum(["har", "mitmproxy"]).describe("Producer capture format"),
+        }),
+        options: z.object({
+            record: z
+                .array(z.coerce.number().int().nonnegative())
+                .optional()
+                .describe("Zero-based producer ordinals; repeat to select several"),
+            sensitiveValue: z
+                .array(z.string().min(1))
+                .default([])
+                .describe("Literal string values explicitly marked sensitive; repeat as needed"),
+        }),
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectWebNetworkCapture, async () => {
+            const result = await service.inspect({
+                capture_path: args.capturePath,
+                format: args.format,
+                sensitive_values: options.sensitiveValue,
+                ...(options.record === undefined
+                    ? {}
+                    : { record_ordinals: options.record }),
+            }, { signal });
+            return result.ok
+                ? result.value
+                : projectAnalysisError(result.error);
+        })),
+    });
+};

package/dist/cli/webRuntimeCommands.js

@@ -0,0 +1,60 @@
+import { Cli, z } from "incur";
+import { createWebRuntimeService } from "../composition/webRuntime.js";
+import { browserCliError } from "../cliBrowserContext.js";
+import { browserScopeOptions, observationDuration, } from "../cliObservationOptions.js";
+import { logCliCommand } from "../cliLogging.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** CLI progress exposes the actual armed point on stderr without corrupting JSON results. */
+const runtimeProgress = {
+    report: async (update) => {
+        process.stderr.write(`${JSON.stringify({ rea_progress: update })}\n`);
+    },
+};
+/** Register public equivalents of the two modular website runtime tools. */
+export const registerWebRuntimeCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.observeWebExecution, {
+        description: "Observe precise page execution; resets counters and temporarily disables optimization",
+        args: z.object({
+            endpoint: z.string().describe("Existing loopback browser CDP endpoint"),
+            targetId: z
+                .string()
+                .describe("Selected page target ID from list-browser-targets"),
+        }),
+        options: z.object({
+            ...browserScopeOptions,
+            observationMs: observationDuration(10_000, 1),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "observe-web-execution", async () => {
+            const result = await withCommandCancellation((signal) => createWebRuntimeService().observe({
+                cdp_endpoint: args.endpoint,
+                target_id: args.targetId,
+                allowed_origins: options.allowedOrigins,
+                observation_ms: options.observationMs,
+            }, { progress: runtimeProgress, signal }));
+            return result.ok ? result.value : browserCliError(result.error);
+        }),
+    });
+    cli.command(CLI_COMMANDS.inspectWebEventListeners, {
+        description: "Inspect native listener source locations on the first main-document CSS match",
+        args: z.object({
+            endpoint: z.string().describe("Existing loopback browser CDP endpoint"),
+            targetId: z
+                .string()
+                .describe("Selected page target ID from list-browser-targets"),
+            selector: z
+                .string()
+                .describe("Native CSS selector; inspect the first main-document match"),
+        }),
+        options: z.object({ ...browserScopeOptions }),
+        run: ({ args, options }) => logCliCommand(logger, "inspect-web-event-listeners", async () => {
+            const result = await withCommandCancellation((signal) => createWebRuntimeService().inspect({
+                cdp_endpoint: args.endpoint,
+                target_id: args.targetId,
+                selector: args.selector,
+                allowed_origins: options.allowedOrigins,
+            }, { signal }));
+            return result.ok ? result.value : browserCliError(result.error);
+        }),
+    });
+};

package/dist/cli/webScriptCommands.js

@@ -0,0 +1,31 @@
+import { Cli, z } from "incur";
+import { exportWebScripts } from "../application/WebScriptExportService.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+/** Register the local captured-script export CLI workflow. */
+export const registerWebScriptCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.exportWebScripts, {
+        description: "Export retained website scripts into an absent directory for static JavaScript analysis",
+        args: z.object({
+            capturePath: z
+                .string()
+                .describe("Absolute path to saved page or scenario capture JSON"),
+            outputDirectory: z
+                .string()
+                .describe("Absolute absent directory for verified scripts and manifest"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.exportWebScripts, async () => {
+            const result = await exportWebScripts({
+                capture_path: args.capturePath,
+                output_directory: args.outputDirectory,
+            });
+            return result.ok
+                ? result.value
+                : {
+                    error: "Script export failed",
+                    ...projectAnalysisError(result.error),
+                };
+        }),
+    });
+};