rea-agents 6.1.0 → 6.3.0

package/dist/cli/processCommands.js

@@ -2,12 +2,13 @@ import { Cli, z } from "incur";
 import { captureProcessScenarioFile, compareProcessEvidenceFiles, isProcessCliFailure, } from "../application/process/ProcessCli.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register direct process capture and comparison commands. */
-export const registerProcessCommands = (cli, logger, environment = process.env) => {
+export const registerProcessCommands = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureProcess, {
         description: "Capture one caller-selected process scenario",
         args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
-        run: ({ args }) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario, environment), isProcessCliFailure),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario, environment, signal), isProcessCliFailure)),
     });
     cli.command(CLI_COMMANDS.compareProcessCaptures, {
         description: "Compare two process capture Evidence JSON files",

package/dist/cli/setupCommands.js

@@ -3,7 +3,8 @@ import { DOCTOR_PROVIDER_IDS, runDoctor, } from "../application/Doctor.js";
 import { isSetupFailure, } from "../application/SetupTypes.js";
 import { runSetup } from "../application/Setup.js";
 import { systemSetupHost } from "../application/SetupHost.js";
-import { isUninstallFailure, runUninstall } from "../application/Uninstall.js";
+import { isUninstallFailure, runUninstall, systemUninstallHost, } from "../application/Uninstall.js";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { isUpdateFailure, runUpdate } from "../application/Update.js";
 import { systemUpdateHost } from "../application/UpdateRuntime.js";
 import { confirmInteractiveSetup, renderInteractiveSetupResult, renderSetupProgress, } from "./interactiveSetup.js";
@@ -17,12 +18,12 @@ const supportedClientSchema = z
     .string()
     .refine((candidate) => supportedClientIds.some((name) => name === candidate), "Unsupported agent integration");
 /** Register setup, doctor, uninstall, and update CLI commands. */
-export const registerSetupCommands = (cli, logger) => {
-    registerSetupCommand(cli, logger);
-    registerDoctorCommand(cli, logger);
-    registerMaintenanceCommands(cli, logger);
+export const registerSetupCommands = (cli, logger, environment) => {
+    registerSetupCommand(cli, logger, environment);
+    registerDoctorCommand(cli, logger, environment);
+    registerMaintenanceCommands(cli, logger, environment);
 };
-const registerSetupCommand = (cli, logger) => {
+const registerSetupCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.setup, {
         description: "Configure agent integrations and optional analysis providers",
         outputPolicy: "agent-only",
@@ -57,10 +58,10 @@ const registerSetupCommand = (cli, logger) => {
                 .describe("Use sequential accessible setup prompts"),
         }),
         alias: { yes: "y" },
-        run: ({ options, formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.setup, () => runSetupCommand({ options, formatExplicit }), isSetupFailure),
+        run: ({ options, formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.setup, () => runSetupCommand({ options, formatExplicit }, environment), isSetupFailure),
     });
 };
-const registerDoctorCommand = (cli, logger) => {
+const registerDoctorCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.doctor, {
         description: "Check whether REA is ready",
         options: z.object({
@@ -78,10 +79,10 @@ const registerDoctorCommand = (cli, logger) => {
                 .optional()
                 .describe("Require the installed REA skill identity to be aligned"),
         }),
-        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target, createSystemDoctorHost(), doctorScope(options))),
+        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target, createSystemDoctorHost(environment), doctorScope(options))),
     });
 };
-const registerMaintenanceCommands = (cli, logger) => {
+const registerMaintenanceCommands = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.uninstall, {
         description: "Remove REA-owned agent configuration and skill files",
         options: z.object({
@@ -91,22 +92,22 @@ const registerMaintenanceCommands = (cli, logger) => {
                 .describe("Also remove REA caches and state"),
         }),
         alias: { purgeData: "purge-data" },
-        run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData), isUninstallFailure),
+        run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData, systemUninstallHost(homeDirectoryFromEnvironment(environment, process.platform), undefined, environment)), isUninstallFailure),
     });
     cli.command(CLI_COMMANDS.update, {
         description: "Update this REA installation and verify the installed release",
-        run: ({ formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.update, () => runUpdate(PRODUCT_IDENTITY.packageVersion, systemUpdateHost(), formatExplicit ? "structured" : "human"), isUpdateFailure),
+        run: ({ formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.update, () => runUpdate(PRODUCT_IDENTITY.packageVersion, systemUpdateHost(undefined, undefined, environment), formatExplicit ? "structured" : "human"), isUpdateFailure),
     });
 };
-const runSetupCommand = async (input) => {
+const runSetupCommand = async (input, environment) => {
     const { options } = input;
     const interactive = setupIsInteractive(options, input.formatExplicit);
     const hasExplicitScope = setupHasExplicitScope(options);
-    const result = await runSetup(setupRunOptions(input, interactive, hasExplicitScope), systemSetupHost(createSystemDoctorHost()), interactive
+    const result = await runSetup(setupRunOptions(input, interactive, hasExplicitScope), systemSetupHost(createSystemDoctorHost(environment), environment), interactive
         ? (actions, context) => confirmInteractiveSetup(actions, options.accessible, context)
         : undefined);
     if (interactive)
-        renderInteractiveSetupResult(result);
+        renderInteractiveSetupResult(result, environment);
     return result;
 };
 const setupRunOptions = (input, interactive, hasExplicitScope) => {

package/dist/cli/streamedJsonOutput.js

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

package/dist/cli/utilityCommands.js

@@ -1,8 +1,7 @@
 import { z } from "incur";
-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 { parseConfig } from "../config/parseConfig.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
@@ -14,10 +13,11 @@ 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);
+export const registerUtilityCommands = (cli, logger, environment, analysis) => {
+    const { runProviderAnalysis } = analysis;
+    registerCapabilityCommands(cli, logger, analysis);
+    registerNativeCommands(cli, logger, runProviderAnalysis);
+    registerNativeCallCommands(cli, logger, runProviderAnalysis);
     for (const [command, operation] of [
         [CLI_COMMANDS.observeNativeUi, "observe_native_ui"],
         [CLI_COMMANDS.captureNativeUiScenario, "capture_native_ui_scenario"],
@@ -97,7 +97,7 @@ const invalidNativeUiScenarioInput = (operation, issues) => ({
     error: "Application workflow failed",
     ...projectAnalysisError(new AnalysisInputError(operation, undefined, issues)),
 });
-const registerCapabilityCommands = (cli, logger) => {
+const registerCapabilityCommands = (cli, logger, { runSessionStatus }) => {
     for (const command of [
         CLI_COMMANDS.capabilities,
         CLI_COMMANDS.providers,
@@ -106,13 +106,11 @@ const registerCapabilityCommands = (cli, logger) => {
             description: command === "capabilities"
                 ? "List provider capabilities and side effects"
                 : "List configured analysis providers",
-            run: () => logCliCommand(logger, command, () => command === CLI_COMMANDS.providers
-                ? runProviderStatus(logger)
-                : runCapabilityStatus(logger)),
+            run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
         });
     }
 };
-const registerNativeCommands = (cli, logger) => {
+const registerNativeCommands = (cli, logger, runProviderAnalysis) => {
     for (const [command, tool] of [
         [CLI_COMMANDS.inspectMacho, "inspect_macho"],
         [CLI_COMMANDS.inspectSignature, "inspect_signature"],
@@ -147,7 +145,7 @@ const registerNativeCommands = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "demangle-swift", () => runProviderAnalysis(args.path, "demangle_swift", { symbols: args.symbols }, logger)),
     });
 };
-const registerReferenceSourceCommand = (cli, logger, environment = process.env) => {
+const registerReferenceSourceCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.importReferenceSource, {
         description: "Import a source tree as historical reference only",
         args: z.object({

package/dist/cli.js

@@ -1,4 +1,7 @@
+import { snapshotEnvironment } from "./process/snapshotEnvironment.js";
+import { createDirectAnalysis } from "./composition/directAnalysis.js";
 import { registerEvmCommands } from "./cli/evmCommands.js";
+import { registerAnalysisViewCommands } from "./cli/analysisViewCommands.js";
 import { registerBinaryDiagnosticsCommands } from "./cli/binaryDiagnosticsCommands.js";
 import { Cli } from "incur";
 import { createLogger, parseLogLevel } from "./logger.js";
@@ -25,12 +28,16 @@ import { registerBrowserScenarioCommands } from "./cliBrowserScenarioCommands.js
 import { registerElectronCommands } from "./cli/electronCommands.js";
 import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRuntimeCommands.js";
 import { registerApplicationCommands } from "./cli/applicationCommands.js";
+import { presentOmittableDefaults } from "./cli/omittableDefaults.js";
+import { streamCliCommandResults, } from "./cli/streamedJsonOutput.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
  * `--mcp` are intercepted by the executable dispatcher before this module loads.
  */
-export const createCli = (environment = process.env, resultOutput) => {
+export const createCli = (selectedEnvironment = process.env, resultOutput) => {
+    const environment = snapshotEnvironment(selectedEnvironment);
+    const analysis = createDirectAnalysis(environment);
     const logger = createLogger("cli", environment.REA_LOG_LEVEL === undefined
         ? "silent"
         : parseLogLevel(environment.REA_LOG_LEVEL));
@@ -43,15 +50,16 @@ export const createCli = (environment = process.env, resultOutput) => {
         },
         sync: false,
     });
-    registerSetupCommands(cli, logger);
-    registerCoreAnalysisCommands(cli, logger, resultOutput);
-    registerUtilityCommands(cli, logger, environment);
+    registerSetupCommands(cli, logger, environment);
+    registerCoreAnalysisCommands(cli, logger, analysis.runDirectAnalysis);
+    registerUtilityCommands(cli, logger, environment, analysis);
     registerEvmCommands(cli, logger, environment);
-    registerArtifactCommands(cli, logger);
-    registerManagedCommands(cli, logger);
+    registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);
+    registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
     registerAndroidCommands(cli, logger, environment);
     registerFirmwareCommands(cli, logger, environment);
     registerBinaryDiagnosticsCommands(cli, logger, environment);
+    registerAnalysisViewCommands(cli, logger);
     registerEvidenceCommands(cli, logger);
     registerProcessCommands(cli, logger, environment);
     registerBrowserCommands(cli, logger);
@@ -62,9 +70,12 @@ export const createCli = (environment = process.env, resultOutput) => {
     registerWebNetworkCaptureCommands(cli, logger, environment);
     registerJavaScriptRecoveryCommands(cli, logger, environment);
     registerAdvancedBrowserCommands(cli, logger);
-    registerBrowserScenarioCommands(cli, logger);
-    registerElectronCommands(cli, logger, resultOutput);
+    registerBrowserScenarioCommands(cli, logger, environment);
+    registerElectronCommands(cli, logger, environment);
     registerJavaScriptRuntimeObservationCommands(cli, logger);
     registerApplicationCommands(cli, logger);
+    presentOmittableDefaults(cli);
+    if (resultOutput !== undefined)
+        streamCliCommandResults(cli, resultOutput);
     return cli;
 };

package/dist/cliBrowserScenarioCommands.js

@@ -11,7 +11,7 @@ import { projectInputIssues } from "./domain/inputIssueProjection.js";
 import { browserScenarioSchema } from "./domain/browserScenario.js";
 const OPERATION = "capture_browser_scenario";
 /** Register the one-shot controlled browser scenario command. */
-export const registerBrowserScenarioCommands = (cli, logger) => {
+export const registerBrowserScenarioCommands = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureBrowserScenario, {
         description: "Run one bounded Playwright browser scenario and return Evidence",
         args: z.object({
@@ -26,7 +26,7 @@ export const registerBrowserScenarioCommands = (cli, logger) => {
             const scenario = browserScenarioSchema.safeParse(resolveCliJsonPaths(input.value, [["browser", "executable_path"]]));
             if (!scenario.success)
                 return cliError(new AnalysisInputError(OPERATION, { cause: scenario.error }, projectInputIssues(scenario.error.issues, input.value)));
-            const result = await captureBrowserScenario(createBrowserScenarioProvider(), scenario.data);
+            const result = await captureBrowserScenario(createBrowserScenarioProvider(environment), scenario.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });

package/dist/cliCommandNames.js

@@ -41,6 +41,7 @@ export const CLI_COMMANDS = Object.freeze({
     inspectManagedArtifact: "inspect-managed-artifact",
     inspectRecordedCrash: "inspect-recorded-crash",
     inspectBinaryLayout: "inspect-binary-layout",
+    inspectAnalysisView: "inspect-analysis-view",
     inspectFirmwareRegions: "inspect-firmware-regions",
     extractFirmware: "extract-firmware",
     inspectAndroidPackage: "inspect-android-package",

package/dist/cliJsonFile.js

@@ -0,0 +1,179 @@
+import { constants } from "node:buffer";
+import { pipeline } from "node:stream/promises";
+import { getHeapStatistics } from "node:v8";
+import parser from "stream-json/parser.js";
+import streamValues from "stream-json/streamers/stream-values.js";
+import { withRegularFile } from "./application/RegularFileRead.js";
+import { JSON_INPUT_RESOURCE_REMEDIATION, parseUtf8Json, } from "./application/Utf8JsonInput.js";
+import { AnalysisInputError, AnalysisResourceConstraintError, } from "./domain/analysisErrorCore.js";
+import { err, ok } from "./domain/result.js";
+const READ_CHUNK_BYTES = 64 * 1024;
+const PACKED_STRING_PART_CODE_UNITS = 64 * 1024;
+// Retain native-parser speed for modest inputs while bounding its extra copies.
+// This selects an implementation; larger files remain accepted through streaming.
+const NATIVE_PARSE_READ_BUDGET = 8 * 1024 * 1024;
+/** Parse strict UTF-8 JSON without requiring a whole-document string. */
+export const readCliJsonFile = (path, operation, signal) => withRegularFile(path, async (handle, stats) => {
+    let found = false;
+    let value;
+    try {
+        const prefix = stats.size <= NATIVE_PARSE_READ_BUDGET
+            ? await readPrefix(handle, stats.size + 1, signal)
+            : undefined;
+        if (prefix?.complete === true) {
+            const parsed = parseUtf8Json(prefix.bytes, operation, path, "cli-json-input");
+            return parsed.ok
+                ? ok(parsed.value)
+                : err(invalidJson(operation, parsed.error, parsed.cause));
+        }
+        await pipeline(decodedChunks(handle, signal, prefix?.bytes), parser.asStream({
+            jsonStreaming: false,
+            streamValues: false,
+            packKeys: false,
+            packStrings: false,
+        }), packJsonStrings(operation, stats.size), streamValues.asStream(), async (rows) => {
+            for await (const row of rows) {
+                if (found ||
+                    typeof row !== "object" ||
+                    row === null ||
+                    !("key" in row) ||
+                    row.key !== 0 ||
+                    !("value" in row))
+                    throw new Error("Unexpected JSON parser result");
+                found = true;
+                value = row.value;
+            }
+        }, signal === undefined ? {} : { signal });
+        return found
+            ? ok(value)
+            : err(invalidJson(operation, "JSON document is empty"));
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisResourceConstraintError)
+            return err(cause);
+        if (cause instanceof TypeError &&
+            "code" in cause &&
+            cause.code === "ERR_ENCODING_INVALID_ENCODED_DATA")
+            return err(invalidJson(operation, "JSON input is not valid UTF-8", cause));
+        if (cause instanceof SyntaxError ||
+            (cause instanceof Error && cause.message.startsWith("Parser ")))
+            return err(invalidJson(operation, cause.message, cause));
+        if (cause instanceof Error &&
+            ((cause instanceof RangeError &&
+                cause.message === "Invalid string length") ||
+                ("code" in cause && cause.code === "ERR_STRING_TOO_LONG")))
+            return err(new AnalysisResourceConstraintError(operation, "memory", "An individual JSON string exceeds the runtime string limit", {
+                input_file_bytes: stats.size,
+                max_string_code_units: constants.MAX_STRING_LENGTH,
+            }, {
+                cause,
+                remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
+            }));
+        throw cause;
+    }
+}, signal);
+const packJsonStrings = (operation, inputFileBytes) => async function* (tokens) {
+    let kind;
+    let length = 0;
+    let value = "";
+    let parts = [];
+    let partLength = 0;
+    for await (const token of tokens) {
+        if (typeof token !== "object" || token === null || !("name" in token))
+            throw new Error("Unexpected JSON parser token");
+        switch (token.name) {
+            case "startKey":
+            case "startString":
+                kind = token.name === "startKey" ? "keyValue" : "stringValue";
+                break;
+            case "stringChunk":
+                if (kind === undefined ||
+                    !("value" in token) ||
+                    typeof token.value !== "string")
+                    throw new Error("Unexpected JSON string fragment");
+                length += token.value.length;
+                if (length > constants.MAX_STRING_LENGTH)
+                    throw new RangeError("Invalid string length");
+                parts.push(token.value);
+                partLength += token.value.length;
+                if (partLength >= PACKED_STRING_PART_CODE_UNITS) {
+                    // The tokenizer emits short fragments. Coalesce them before retaining
+                    // a string so millions of substring/rope nodes cannot exhaust the heap
+                    // before the native string-length constraint can be reported.
+                    requireStringAssemblyHeadroom(operation, inputFileBytes, length);
+                    value += parts.join("");
+                    parts = [];
+                    partLength = 0;
+                }
+                break;
+            case "endKey":
+            case "endString":
+                if (kind === undefined)
+                    throw new Error("Unexpected JSON string end");
+                requireStringAssemblyHeadroom(operation, inputFileBytes, length);
+                yield { name: kind, value: value + parts.join("") };
+                kind = undefined;
+                length = 0;
+                value = "";
+                parts = [];
+                partLength = 0;
+                break;
+            default:
+                yield token;
+        }
+    }
+};
+const requireStringAssemblyHeadroom = (operation, inputFileBytes, stringCodeUnits) => {
+    if (stringCodeUnits < PACKED_STRING_PART_CODE_UNITS)
+        return;
+    const heap = getHeapStatistics();
+    // Concatenation or key interning may flatten the retained rope. Reserve its
+    // UTF-16 representation and the next coalesced part before that allocation.
+    const requiredBytes = 2 * (stringCodeUnits + PACKED_STRING_PART_CODE_UNITS);
+    if (requiredBytes > heap.total_available_size)
+        throw new AnalysisResourceConstraintError(operation, "memory", "Insufficient heap headroom to assemble a complete JSON string", {
+            input_file_bytes: inputFileBytes,
+            string_code_units: stringCodeUnits,
+            string_assembly_headroom_bytes: requiredBytes,
+            available_heap_bytes: heap.total_available_size,
+            heap_size_limit_bytes: heap.heap_size_limit,
+        }, {
+            remediationAction: JSON_INPUT_RESOURCE_REMEDIATION,
+        });
+};
+async function* decodedChunks(handle, signal, prefix) {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    if (prefix !== undefined)
+        for (let offset = 0; offset < prefix.length; offset += READ_CHUNK_BYTES) {
+            signal?.throwIfAborted();
+            yield decoder.decode(prefix.subarray(offset, offset + READ_CHUNK_BYTES), {
+                stream: true,
+            });
+        }
+    const bytes = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+    while (true) {
+        signal?.throwIfAborted();
+        const read = await handle.read(bytes, 0, bytes.length, null);
+        signal?.throwIfAborted();
+        if (read.bytesRead === 0)
+            break;
+        yield decoder.decode(bytes.subarray(0, read.bytesRead), { stream: true });
+    }
+    yield decoder.decode();
+}
+const readPrefix = async (handle, size, signal) => {
+    const bytes = Buffer.allocUnsafe(size);
+    let offset = 0;
+    while (offset < bytes.length) {
+        signal?.throwIfAborted();
+        const read = await handle.read(bytes, offset, bytes.length - offset, null);
+        signal?.throwIfAborted();
+        if (read.bytesRead === 0)
+            return { bytes: bytes.subarray(0, offset), complete: true };
+        offset += read.bytesRead;
+    }
+    // The file grew after admission. Continue from this same handle, preserving
+    // the prefix already read rather than reopening or dropping its bytes.
+    return { bytes, complete: false };
+};
+const invalidJson = (operation, message, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [{ path: [], reason: "invalid_format", expected: "JSON", message }]);