rea-agents 6.4.0 → 6.7.0

package/dist/jeb/JebProvider.js

@@ -1,11 +1,13 @@
+import { JebMcpAcquisitionCleanupFailure, JebMcpPhysicalFailure, } from "./JebMcpConnectionOwner.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { z } from "zod";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
 import { jebResultSchemas } from "../domain/jeb/jebAnalysis.js";
-import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisProtocolError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisProtocolError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { err, ok } from "../domain/result.js";
 import { parseJebMcpEndpoint, DEFAULT_JEB_MCP_ENDPOINT, } from "./JebMcpEndpoint.js";
-import { createStreamableHttpJebMcpConnection, } from "./JebMcpConnection.js";
+import { createStreamableHttpJebMcpConnection, JEB_ENGINE_TOOLS, } from "./JebMcpConnection.js";
 export const JEB_PROVIDER_IDENTITY = {
     id: "jeb",
     name: "JEB",
@@ -40,14 +42,12 @@ const openProject = z
     success: z.literal(true),
     name: z.string().nullish(),
     creation_datetime: z.string().nullish(),
-    input_files: z
-        .array(z.object({
+    input_files: z.array(z.object({
         file_name: z.string(),
         file_size: z.number().int().nonnegative(),
         contents_sha256_hash: z.string(),
-    }))
-        .optional(),
-    units: z.array(unitEntry).optional(),
+    })),
+    units: z.array(unitEntry),
 })
     .passthrough();
 const listUnits = z
@@ -70,27 +70,39 @@ const refusalReason = (payload, fallback) => {
 export class JebProvider {
     #connection;
     #endpoint;
-    #identity = JEB_PROVIDER_IDENTITY;
-    #guiClient = null;
+    #clientInformation;
+    #identity(version) {
+        return {
+            ...JEB_PROVIDER_IDENTITY,
+            version: version ?? null,
+        };
+    }
     constructor(options = {}) {
         const environment = options.environment ?? {};
         const endpoint = parseJebMcpEndpoint(environment.REA_JEB_MCP_URL);
         if (!endpoint.ok)
             throw endpoint.error;
         this.#endpoint = endpoint.value;
-        this.#connection = (options.connectionFactory ??
-            ((url) => createStreamableHttpJebMcpConnection(url)))(this.#endpoint);
+        const createConnection = options.connectionFactory ?? createStreamableHttpJebMcpConnection;
+        this.#connection =
+            options.requestTimeoutMs === undefined
+                ? createConnection(this.#endpoint)
+                : createConnection(this.#endpoint, {
+                    requestTimeoutMs: options.requestTimeoutMs,
+                });
     }
     async inspectAvailability(signal) {
         try {
-            await this.#refreshClientInformation(signal);
+            const tools = new Set(await this.#connection.listTools(signal));
+            const { information } = await this.#refreshClientInformation("inspect_jeb_client", signal);
             return {
                 status: "available",
                 code: null,
                 reason: null,
+                supportedOperations: Object.keys(JEB_ENGINE_TOOLS).filter((operation) => tools.has(JEB_ENGINE_TOOLS[operation])),
                 diagnostics: {
                     endpoint: this.#endpoint.toString(),
-                    engine_version: this.#identity.version,
+                    engine_version: information.version ?? null,
                 },
             };
         }
@@ -112,28 +124,21 @@ export class JebProvider {
     }
     async execute(request, options) {
         if (options?.signal?.aborted === true)
-            return err(new AnalysisCancelledError(request.operation));
+            return err(new AnalysisCancelledError(request.operation, {
+                cause: options.signal.reason,
+            }));
         try {
             const execution = await this.#dispatch(request, options?.signal);
-            if (options?.signal?.aborted)
-                return err(new AnalysisCancelledError(request.operation));
-            if (execution.ok)
-                this.#identity = {
-                    ...this.#identity,
-                    version: execution.value.provider.version,
-                };
             return execution;
         }
         catch (cause) {
-            if (options?.signal?.aborted)
-                return err(new AnalysisCancelledError(request.operation, { cause }));
             return err(this.#providerFailure(request.operation, cause));
         }
     }
     async #dispatch(request, signal) {
         const cancelled = (operation) => {
             if (signal?.aborted === true)
-                throw new AnalysisCancelledError(operation);
+                throw new AnalysisCancelledError(operation, { cause: signal.reason });
         };
         switch (request.operation) {
             case "inspect_jeb_client": {
@@ -154,39 +159,29 @@ export class JebProvider {
             }
         }
     }
-    async #engine(signal) {
-        await this.#requireClientInformation(signal);
+    async #engine(operation, signal) {
+        const information = this.#clientInformation ??
+            (await this.#refreshClientInformation(operation, signal)).information;
         return {
             name: "jeb",
-            version: this.#identity.version,
+            version: information.version ?? null,
             endpoint: this.#endpoint.toString(),
-            gui_client: this.#guiClient,
+            gui_client: information.gui_client ?? null,
         };
     }
-    async #requireClientInformation(signal) {
-        if (this.#identity.version !== null)
-            return;
-        await this.#refreshClientInformation(signal);
-    }
-    async #refreshClientInformation(signal) {
+    async #refreshClientInformation(operation, signal) {
         if (signal?.aborted === true)
-            throw new AnalysisCancelledError("inspect_jeb_client");
+            throw new AnalysisCancelledError(operation, { cause: signal.reason });
         const payload = await this.#connection.call("get_client_information", {}, signal);
-        const information = clientInformation.parse(this.#requireSuccess(payload, "inspect_jeb_client"));
-        this.#identity = {
-            ...this.#identity,
-            version: information.version ?? null,
+        const information = clientInformation.parse(this.#requireSuccess(payload, operation));
+        this.#clientInformation = {
+            version: information.version,
+            gui_client: information.gui_client,
         };
-        this.#guiClient = information.gui_client ?? null;
+        return { information, payload };
     }
     async #inspectClient(signal) {
-        const payload = await this.#connection.call("get_client_information", {}, signal);
-        const information = clientInformation.parse(this.#requireSuccess(payload, "inspect_jeb_client"));
-        this.#identity = {
-            ...this.#identity,
-            version: information.version ?? null,
-        };
-        this.#guiClient = information.gui_client ?? null;
+        const { information, payload } = await this.#refreshClientInformation("inspect_jeb_client", signal);
         const result = jebResultSchemas.inspect_jeb_client.parse({
             engine: {
                 name: "jeb",
@@ -197,7 +192,7 @@ export class JebProvider {
             startup_ts: information.startup_ts ?? null,
             message: information.message ?? null,
         });
-        return ok(createAnalysisExecution(result, this.#identity, {
+        return ok(createAnalysisExecution(result, this.#identity(information.version), {
             rawResult: payload,
             limitations: information.version === undefined
                 ? ["The engine did not report its version."]
@@ -209,15 +204,15 @@ export class JebProvider {
             file_path: request.input.path,
         }, signal);
         const opened = openProject.parse(this.#requireSuccess(payload, request.operation));
-        const engine = await this.#engine(signal);
+        const engine = await this.#engine(request.operation, signal);
         const result = jebResultSchemas.open_jeb_project.parse({
             engine,
             project_name: opened.name ?? null,
             creation_datetime: opened.creation_datetime ?? null,
-            input_files: opened.input_files ?? [],
-            units: opened.units ?? [],
+            input_files: opened.input_files,
+            units: opened.units,
         });
-        return ok(createAnalysisExecution(result, this.#identity, {
+        return ok(createAnalysisExecution(result, this.#identity(engine.version), {
             rawResult: payload,
             limitations: [
                 "JEB resolves and analyzes the artifact on the engine host; REA did not open the target itself.",
@@ -234,7 +229,7 @@ export class JebProvider {
         }, signal);
         const listed = listUnits.parse(this.#requireSuccess(payload, request.operation));
         const units = listed.units;
-        const engine = await this.#engine(signal);
+        const engine = await this.#engine(request.operation, signal);
         const result = jebResultSchemas.list_jeb_units.parse({
             engine,
             filter: filter ?? null,
@@ -244,7 +239,7 @@ export class JebProvider {
             units,
             coverage: units.length < count ? "complete" : "partial",
         });
-        return ok(createAnalysisExecution(result, this.#identity, {
+        return ok(createAnalysisExecution(result, this.#identity(engine.version), {
             rawResult: payload,
             limitations: [
                 "The engine caps unit pages at 100; a full page means more units may exist.",
@@ -259,7 +254,7 @@ export class JebProvider {
             ...(unit_path === undefined ? {} : { unit_path }),
         }, signal);
         const decompiled = decompiledItem.parse(this.#requireSuccess(payload, request.operation));
-        const engine = await this.#engine(signal);
+        const engine = await this.#engine(request.operation, signal);
         const result = jebResultSchemas.decompile_jeb_item.parse({
             engine,
             unit_path: unit_path ?? null,
@@ -267,7 +262,7 @@ export class JebProvider {
             item_kind,
             text: decompiled.text,
         });
-        return ok(createAnalysisExecution(result, this.#identity, {
+        return ok(createAnalysisExecution(result, this.#identity(engine.version), {
             rawResult: payload,
             limitations: unit_path === undefined
                 ? [
@@ -287,12 +282,41 @@ export class JebProvider {
         return payload;
     }
     #providerFailure(operation, cause) {
+        if (cause instanceof JebMcpAcquisitionCleanupFailure)
+            return analysisErrorWithCleanupFailure(this.#providerFailure(operation, cause.primaryFailure), cause.cleanupFailure, operation)
+                .bindCleanupDependencies([cause.cleanupFailure])
+                .bindCleanupResourceOwner(cause.cleanupFailure);
+        if (cause instanceof AnalysisCancelledError ||
+            cause instanceof AnalysisTimeoutError) {
+            const options = {
+                cause: cause.cause,
+                diagnostics: cause.diagnostics,
+                capturedOutput: cause.capturedOutput,
+                cleanup: cause.cleanup,
+                partialObservation: cause.partialObservation,
+            };
+            const failure = cause instanceof AnalysisTimeoutError
+                ? new AnalysisTimeoutError(operation, cause.timeoutMs, {
+                    ...options,
+                    ...(cause.userMessage === undefined
+                        ? {}
+                        : { userMessage: cause.userMessage }),
+                    ...(cause.remediationAction === undefined
+                        ? {}
+                        : { remediationAction: cause.remediationAction }),
+                })
+                : new AnalysisCancelledError(operation, options);
+            return failure
+                .bindCleanupDependencies([cause])
+                .bindCleanupResourceOwner(cause);
+        }
         if (cause instanceof AnalysisError)
             return cause;
         if (cause instanceof z.ZodError)
             return new AnalysisProtocolError("JEB omitted or malformed required observation fields", { cause });
-        return new AnalysisCapabilityUnavailableError("jeb", operation, cause instanceof Error ? cause.message : String(cause), {
-            cause: cause instanceof Error ? cause : undefined,
+        const physical = cause instanceof JebMcpPhysicalFailure ? cause.cause : cause;
+        return new AnalysisCapabilityUnavailableError("jeb", operation, physical instanceof Error ? physical.message : String(physical), {
+            cause,
             userMessage: `Start a JEB client serving MCP (default ${DEFAULT_JEB_MCP_ENDPOINT}) or set REA_JEB_MCP_URL to the running endpoint.`,
         });
     }

package/dist/kuna/KunaAddress.js

@@ -0,0 +1,11 @@
+/** Normalize a u64 selector without allocating a BigInt for unbounded digits. */
+export const normalizeKunaAddress = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^0x0*([0-9a-f]{1,16})$/iu.exec(value);
+    return match?.[1] === undefined
+        ? undefined
+        : `0x${BigInt(`0x${match[1]}`).toString(16)}`;
+};
+/** Sort canonical hexadecimal addresses numerically without BigInt allocations. */
+export const compareKunaAddresses = (left, right) => left.length - right.length || (left < right ? -1 : left > right ? 1 : 0);

package/dist/kuna/KunaCommand.js

@@ -0,0 +1,217 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { OwnedCommandFailure, runOwnedCommand, } from "../process/OwnedCommand.js";
+import { hashStableFile } from "../filesystem/StableFileHash.js";
+import { RegularFileCleanupFailure, regularFileCancellation, } from "../filesystem/OwnedRegularFile.js";
+import { kunaChildEnvironment, } from "./KunaInstallation.js";
+import { KUNA_PROVIDER_ID } from "./KunaRelease.js";
+/**
+ * `kuna functions --json` costs ~210 bytes per function; this admits about
+ * 600,000 functions, above the 392,814 of the largest image Kuna documents.
+ */
+export const KUNA_INVENTORY_OUTPUT_BYTES = 128 * 1024 * 1024;
+const message = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Preserve the operation's typed failure while attaching descriptor cleanup. */
+export const kunaFileCleanupError = (failure, operation) => {
+    const cleanup = new ProviderCleanupError(KUNA_PROVIDER_ID, [failure.path], { reason: message(failure.cleanupCause) }, { cause: failure, operation });
+    const cancellation = regularFileCancellation(failure);
+    if (cancellation !== undefined)
+        return new AnalysisCancelledError(operation, {
+            cause: cancellation.reason,
+            cleanup: {
+                reason: message(failure.cleanupCause),
+                resources: [failure.path],
+            },
+        });
+    if (failure.outcome.kind === "completed")
+        return cleanup;
+    const primaryCause = failure.outcome.cause;
+    const primary = primaryCause instanceof AnalysisError
+        ? primaryCause
+        : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
+            cause: primaryCause,
+            userMessage: `Kuna ${operation} failed: ${message(primaryCause)}`,
+        });
+    return analysisErrorWithCleanupFailure(primary, cleanup, operation);
+};
+/** File metadata that, unchanged, lets a verified digest stand without re-hashing. */
+const verifiedExecutables = new Map();
+/**
+ * Confirm the executable still has the digest its analysis profile committed,
+ * so no answer names one Kuna build while another produced it.
+ */
+const verifyExecutable = async (installation, signal, retainFailedFileClose) => {
+    const status = await stat(installation.executable, { bigint: true });
+    const identity = [
+        status.dev,
+        status.ino,
+        status.size,
+        status.mtimeNs,
+        status.ctimeNs,
+    ].join(":");
+    const known = verifiedExecutables.get(installation.executable);
+    let sha256 = known?.identity === identity ? known.sha256 : undefined;
+    if (sha256 === undefined) {
+        sha256 = (await hashStableFile(installation.executable, {
+            signal,
+            retainFailedClose: (owner) => retainFailedFileClose(owner, installation.executable),
+        })).sha256;
+        verifiedExecutables.set(installation.executable, { identity, sha256 });
+    }
+    return sha256 === installation.sha256 ? undefined : sha256;
+};
+/** Run Kuna under an owned process group with REA's environment and limits. */
+export const runKunaCommand = async (request) => {
+    const { installation } = request;
+    try {
+        const changed = await verifyExecutable(installation, request.signal, request.retainFailedFileClose);
+        if (changed !== undefined)
+            return {
+                kind: "failed",
+                error: new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {
+                    userMessage: `${installation.executable} changed after this target was opened; reopen the target so REA probes the current Kuna executable.`,
+                    diagnostics: {
+                        expected_sha256: installation.sha256,
+                        observed_sha256: changed,
+                    },
+                }),
+            };
+    }
+    catch (cause) {
+        if (cause instanceof RegularFileCleanupFailure) {
+            return {
+                kind: "failed",
+                error: kunaFileCleanupError(cause, request.operation),
+                fileCleanupFailure: cause,
+            };
+        }
+        const cancellation = regularFileCancellation(cause);
+        return {
+            kind: "failed",
+            error: cancellation !== undefined
+                ? new AnalysisCancelledError(request.operation, {
+                    cause: cancellation.reason,
+                })
+                : new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {
+                    cause,
+                    userMessage: `Cannot verify ${installation.executable}: ${message(cause)}`,
+                }),
+        };
+    }
+    try {
+        const snapshot = await runOwnedCommand({
+            command: installation.executable,
+            arguments: request.arguments,
+            runId: `rea-kuna-${randomUUID()}`,
+            // A script's process reports its interpreter, not the configured path.
+            ...(installation.script ? { expectedCommand: null } : {}),
+            cwd: request.workspace,
+            hostEnvironment: kunaChildEnvironment(installation.configuration),
+            env: { TMPDIR: request.workspace },
+        }, {
+            timeoutMs: Math.max(1, request.timeoutMs),
+            diagnosticBytes: request.outputBytes,
+            ...(request.stdout === undefined ? {} : { stdout: request.stdout }),
+        }, {
+            signal: request.signal,
+            ...(request.launcher === undefined
+                ? {}
+                : { launcher: request.launcher }),
+        });
+        return { kind: "ok", snapshot };
+    }
+    catch (cause) {
+        return commandFailure(cause, request);
+    }
+};
+/** Copy a file and return the SHA-256 of exactly the bytes copied. */
+export const copyAndHash = async (source, destination, signal) => {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(source), new Transform({
+        transform(chunk, _encoding, callback) {
+            hash.update(chunk);
+            callback(null, chunk);
+        },
+    }), createWriteStream(destination, { flags: "wx", mode: 0o600 }), { signal });
+    return hash.digest("hex");
+};
+/** Map an owned-command failure to its typed error, keeping unproven cleanup owned. */
+const commandFailure = (cause, request) => {
+    const { operation } = request;
+    const subcommand = request.arguments[0] ?? "";
+    if (!(cause instanceof OwnedCommandFailure))
+        return {
+            kind: "failed",
+            error: new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
+                cause,
+                userMessage: `Cannot run ${request.installation.executable}: ${message(cause)}`,
+            }),
+        };
+    const snapshot = cause.snapshot;
+    const capturedOutput = snapshot === null
+        ? undefined
+        : {
+            // Output can be evidence-sized, not diagnostic-sized; keep only its
+            // tail. Output that overflowed its buffer is a cut-off document
+            // whose tail explains nothing, so none of it is kept.
+            stdout: cause.reason === "output-limit"
+                ? ""
+                : snapshot.stdout.text.slice(-4096),
+            stderr: snapshot.stderr.text,
+            truncated: snapshot.diagnosticTruncated === true ||
+                snapshot.outputIncomplete === true ||
+                snapshot.stdout.text.length > 4096,
+            exit_code: snapshot.exitCode ?? null,
+            signal: snapshot.signal ?? null,
+        };
+    const details = {
+        cause,
+        ...(capturedOutput === undefined ? {} : { capturedOutput }),
+    };
+    let primary;
+    if (cause.reason === "cancelled")
+        primary = new AnalysisCancelledError(operation, {
+            ...details,
+            cause: cause.cancellation?.reason,
+        });
+    else if (cause.reason === "timeout") {
+        const { setting, ms } = request.deadline;
+        primary = new AnalysisTimeoutError(operation, ms, {
+            ...details,
+            userMessage: `kuna ${subcommand} did not finish within ${setting} (${String(ms)} ms).`,
+            // The same run takes as long again, so only a longer deadline helps.
+            remediationAction: `Raise ${setting} in the environment that starts REA, then restart REA; it reads Kuna settings when it starts.${subcommand === "decompile"
+                ? " Within a session, pseudocode is also read from the project export once it finishes."
+                : ""}`,
+        });
+    }
+    // The same input overflows the same fixed buffer; waiting cannot help.
+    else if (cause.reason === "output-limit")
+        primary = new AnalysisResourceConstraintError(operation, "memory", `kuna ${subcommand} wrote more than ${String(request.outputBytes)} bytes of output.`, { output_limit_bytes: request.outputBytes }, {
+            ...details,
+            remediationAction: `REA buffers at most ${String(request.outputBytes)} bytes of kuna ${subcommand} output, so repeating this request for this target fails the same way. Use another provider for it.`,
+        });
+    else {
+        const exitCode = capturedOutput?.exit_code;
+        primary = new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
+            ...details,
+            userMessage: `kuna ${subcommand} failed${exitCode === undefined || exitCode === null ? "" : ` with exit code ${String(exitCode)}`}: ${capturedOutput?.stderr.trim().split("\n").at(-1) || cause.message}`,
+        });
+    }
+    if (cause.cleanupFailure !== null)
+        return {
+            kind: "retained",
+            processResources: cause.resources,
+            error: new ProviderCleanupError(KUNA_PROVIDER_ID, [...cause.resources, request.workspace], { reason: cause.cleanupFailure }, { ...details, operation, cleanupPrimary: primary }),
+            owner: cause.cleanupOwner,
+        };
+    return { kind: "failed", error: primary };
+};

package/dist/kuna/KunaConfiguration.js

@@ -0,0 +1,90 @@
+import { isAbsolute, join } from "node:path";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
+import { providerStartupTimeoutSchema } from "../config/providerStartupTimeout.js";
+import { err, ok } from "../domain/result.js";
+import { KUNA_COMMAND_REMEDIATION, KUNA_UNSUPPORTED_HOST_REMEDIATION, } from "./KunaRelease.js";
+/** Kuna caps its own decode lanes and worker pool at 32. */
+const MAX_KUNA_JOBS = 32;
+/**
+ * A 1.4 MB sqlite3 shell exported serially in 66-108 s on Apple M-series and
+ * Linux hosts; thirty minutes admits images an order of magnitude larger
+ * without an unbounded run. Larger images need a raised deadline or more jobs.
+ */
+const DEFAULT_PROJECT_TIMEOUT_MS = 30 * 60 * 1000;
+/** One function decompiles in well under a second; sqlite3VdbeExec (42 KB) took 15-25 s. */
+const DEFAULT_FUNCTION_TIMEOUT_MS = 120_000;
+/**
+ * A serial (`--jobs 1`) export is Kuna's reference answer: it decompiles
+ * callees before callers, which recovers prototypes that parallel workers
+ * cannot. Measured on coreutils sort, 40-60% of functions differ otherwise.
+ */
+const DEFAULT_JOBS = 1;
+/** Measured sqlite3 exports occupy ~25 MiB; four GiB retains many projects. */
+const DEFAULT_CACHE_MAX_BYTES = 4 * 1024 ** 3;
+/** One project needs its .c, .h, .asm, inventory and manifest; refuse smaller caps. */
+const MIN_CACHE_MAX_BYTES = 1024 ** 2;
+/** Single-function decompiles and the standalone inventory. */
+export const kunaFunctionDeadline = (configuration) => ({
+    setting: "REA_KUNA_TIMEOUT_MS",
+    ms: configuration.functionTimeoutMs,
+});
+/** The project export and whole-program string, graph and xref scans. */
+export const kunaProjectDeadline = (configuration) => ({
+    setting: "REA_KUNA_PROJECT_TIMEOUT_MS",
+    ms: configuration.projectTimeoutMs,
+});
+const failure = (code, reason, setting = null) => err({ code, reason, setting });
+const positiveInteger = (value) => /^[1-9]\d*$/u.test(value) && Number.isSafeInteger(Number(value))
+    ? Number(value)
+    : undefined;
+/** Per-user cache directory that REA owns for Kuna on this host. */
+const defaultCacheRoot = (environment, platform) => {
+    const home = homeDirectoryFromEnvironment(environment, platform);
+    if (platform === "darwin")
+        return join(home, "Library", "Caches", "rea", "kuna");
+    const xdg = environment.XDG_CACHE_HOME;
+    return join(xdg !== undefined && isAbsolute(xdg) ? xdg : join(home, ".cache"), "rea", "kuna");
+};
+/** Parse the Kuna settings without touching the filesystem or the executable. */
+export const readKunaConfiguration = (environment, platform = process.platform) => {
+    const command = environment.REA_KUNA_COMMAND;
+    if (command === undefined || command.length === 0)
+        return failure("not_configured", KUNA_COMMAND_REMEDIATION);
+    if (!isAbsolute(command))
+        return failure("open_options_invalid", `REA_KUNA_COMMAND must be an absolute path; received ${command}. ${KUNA_COMMAND_REMEDIATION}`, "REA_KUNA_COMMAND");
+    if (platform !== "darwin" && platform !== "linux")
+        return failure("unsupported_host", KUNA_UNSUPPORTED_HOST_REMEDIATION);
+    const cacheRoot = environment.REA_KUNA_CACHE_DIR;
+    if (cacheRoot !== undefined && !isAbsolute(cacheRoot))
+        return failure("open_options_invalid", `REA_KUNA_CACHE_DIR must be an absolute directory; received ${cacheRoot}.`, "REA_KUNA_CACHE_DIR");
+    const rawMaxBytes = environment.REA_KUNA_CACHE_MAX_BYTES;
+    const cacheMaxBytes = rawMaxBytes === undefined
+        ? DEFAULT_CACHE_MAX_BYTES
+        : positiveInteger(rawMaxBytes);
+    if (cacheMaxBytes === undefined || cacheMaxBytes < MIN_CACHE_MAX_BYTES)
+        return failure("open_options_invalid", `REA_KUNA_CACHE_MAX_BYTES must be a decimal byte count of at least ${String(MIN_CACHE_MAX_BYTES)}; received ${String(rawMaxBytes)}.`, "REA_KUNA_CACHE_MAX_BYTES");
+    const rawTimeout = environment.REA_KUNA_PROJECT_TIMEOUT_MS;
+    const timeout = rawTimeout === undefined
+        ? undefined
+        : providerStartupTimeoutSchema.safeParse(rawTimeout);
+    if (timeout !== undefined && !timeout.success)
+        return failure("open_options_invalid", `REA_KUNA_PROJECT_TIMEOUT_MS must be a decimal millisecond count from 1 to 2147483647; received ${String(rawTimeout)}.`, "REA_KUNA_PROJECT_TIMEOUT_MS");
+    const rawFunctionTimeout = environment.REA_KUNA_TIMEOUT_MS;
+    const functionTimeout = rawFunctionTimeout === undefined
+        ? undefined
+        : providerStartupTimeoutSchema.safeParse(rawFunctionTimeout);
+    if (functionTimeout !== undefined && !functionTimeout.success)
+        return failure("open_options_invalid", `REA_KUNA_TIMEOUT_MS must be a decimal millisecond count from 1 to 2147483647; received ${String(rawFunctionTimeout)}.`, "REA_KUNA_TIMEOUT_MS");
+    const rawJobs = environment.REA_KUNA_JOBS;
+    const jobs = rawJobs === undefined ? DEFAULT_JOBS : positiveInteger(rawJobs);
+    if (jobs === undefined || jobs > MAX_KUNA_JOBS)
+        return failure("open_options_invalid", `REA_KUNA_JOBS must be an integer from 1 to ${String(MAX_KUNA_JOBS)}; received ${String(rawJobs)}.`, "REA_KUNA_JOBS");
+    return ok({
+        command,
+        cacheRoot: cacheRoot ?? defaultCacheRoot(environment, platform),
+        cacheMaxBytes,
+        projectTimeoutMs: timeout?.data ?? DEFAULT_PROJECT_TIMEOUT_MS,
+        functionTimeoutMs: functionTimeout?.data ?? DEFAULT_FUNCTION_TIMEOUT_MS,
+        jobs,
+    });
+};