rea-agents 6.1.0 → 6.2.0

package/dist/inspector/V8InspectorProvider.js

@@ -4,13 +4,11 @@ import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/browserObservationErrors.js";
 import { err, ok } from "../domain/result.js";
-import { numberValue, recordValue, cdpStringValue, delayWithCancellation, } from "../browser/CdpCaptureValues.js";
+import { numberValue, recordValue, cdpStringValue, scriptMetadataValues, delayWithCancellation, } from "../browser/CdpCaptureValues.js";
 import { CdpConnection } from "../browser/CdpConnection.js";
 import { authorizeRuntimeTargetLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
 import { createInspectorExclusionCounts, describeInspectorTargetLimitations, finalizeInspectorCapture, } from "./V8InspectorCaptureProjection.js";
 import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
-/** Public identity committed by passive V8 Inspector observations. */
-export { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
 import { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
 /** Maximum decoded CDP message accepted while observing one Inspector target. */
 export const INSPECTOR_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
@@ -68,7 +66,7 @@ export class V8InspectorProvider {
                 assertRuntimeKind(target, input.runtime_kind);
             connection = await CdpConnection.connect(target.webSocketUrl, "observe_javascript_runtime", options.signal, { maxPayloadBytes: INSPECTOR_MAX_PAYLOAD_BYTES });
             const state = emptyCaptureState();
-            const removeListener = connection.onEvent((event) => ingestEvent(event, input, state));
+            const removeListener = connection.onEvent((event) => ingestEvent(event, state));
             try {
                 await connection.send("Runtime.enable", {}, undefined, options.signal);
                 await connection.send("Debugger.enable", {}, undefined, options.signal);
@@ -102,7 +100,11 @@ export class V8InspectorProvider {
                 }
         }
         if (cleanupFailed) {
-            return err(inspectorCleanupError(primaryFailure, cleanupFailure, failed));
+            return err(inspectorCleanupError(primaryFailure, cleanupFailure, failed, outcome?.ok === true
+                ? outcome.value
+                : outcome?.ok === false
+                    ? outcome.error.partialObservation
+                    : undefined));
         }
         return (outcome ??
             err(new BrowserObservationError("observe_javascript_runtime", "protocol_error")));
@@ -132,11 +134,21 @@ export const closeInspectorConnection = async (connection, signal) => {
             signal.removeEventListener("abort", onAbort);
     }
 };
-export const inspectorCleanupError = (primaryFailure, cleanupFailure, hasPrimaryFailure) => {
+export const inspectorCleanupError = (primaryFailure, cleanupFailure, hasPrimaryFailure, partialObservation) => {
     const cause = hasPrimaryFailure
         ? new AggregateError([primaryFailure, cleanupFailure], "Inspector observation and cleanup both failed")
         : cleanupFailure;
-    return new BrowserObservationError("observe_javascript_runtime", "cleanup_failed", { cause });
+    const cleanupReason = cleanupFailure instanceof Error
+        ? cleanupFailure.message
+        : String(cleanupFailure);
+    return new BrowserObservationError("observe_javascript_runtime", "cleanup_failed", {
+        cause,
+        cleanup: {
+            reason: cleanupReason,
+            resources: ["browser_transport"],
+        },
+        ...(partialObservation === undefined ? {} : { partialObservation }),
+    });
 };
 const projectTarget = (target) => ({
     target_id: target.id,
@@ -177,7 +189,7 @@ const emptyCaptureState = () => ({
     truncated: false,
     truncationReasons: new Set(),
 });
-const ingestEvent = (event, input, state) => {
+const ingestEvent = (event, state) => {
     if (event.method !== "Debugger.scriptParsed" &&
         event.method !== "Debugger.scriptFailedToParse" &&
         event.method !== "Runtime.executionContextCreated" &&
@@ -186,7 +198,7 @@ const ingestEvent = (event, input, state) => {
         return;
     state.eventsObserved += 1;
     if (event.method === "Debugger.scriptParsed") {
-        ingestScript(event, input, state);
+        ingestScript(event, state);
         return;
     }
     if (event.method === "Debugger.scriptFailedToParse") {
@@ -194,9 +206,9 @@ const ingestEvent = (event, input, state) => {
         retainEvent(state, 0);
         return;
     }
-    ingestContext(event, input, state);
+    ingestContext(event, state);
 };
-const ingestScript = (event, input, state) => {
+const ingestScript = (event, state) => {
     state.scriptsObserved += 1;
     const value = recordValue(event.params);
     const rawUrl = cdpStringValue(value?.url);
@@ -205,19 +217,20 @@ const ingestScript = (event, input, state) => {
         retainEvent(state, 0);
         return;
     }
+    const metadata = scriptMetadataValues(value);
     const draft = {
         rawUrl,
         executionContextKey: contextKey(value?.executionContextId),
-        cdpHash: cdpStringValue(value?.hash) ?? null,
-        length: nonnegativeInteger(value?.length),
-        isModule: value?.isModule === true,
+        cdpHash: metadata.hash,
+        length: metadata.length,
+        isModule: metadata.isModule,
     };
     const bytes = retainedMetadataBytes(draft);
     if (!retainEvent(state, bytes))
         return;
     state.scripts.push(draft);
 };
-const ingestContext = (event, input, state) => {
+const ingestContext = (event, state) => {
     if (event.method === "Runtime.executionContextsCleared") {
         let byteDelta = 0;
         for (const context of state.contexts.values()) {
@@ -243,17 +256,18 @@ const ingestContext = (event, input, state) => {
         retainEvent(state, 0);
         return;
     }
-    const origin = event.method === "Runtime.executionContextCreated"
-        ? (cdpStringValue(runtimeContext?.origin) ?? null)
-        : null;
+    const previous = state.contexts.get(key);
+    const created = event.method === "Runtime.executionContextCreated";
     const draft = {
         contextKey: key,
-        state: event.method === "Runtime.executionContextCreated"
-            ? "created"
-            : "destroyed",
-        origin: origin === "" ? null : origin,
+        state: created ? "created" : "destroyed",
+        name: created
+            ? (cdpStringValue(runtimeContext?.name) ?? null)
+            : (previous?.name ?? null),
+        origin: created
+            ? (cdpStringValue(runtimeContext?.origin) ?? null)
+            : (previous?.origin ?? null),
     };
-    const previous = state.contexts.get(key);
     const bytes = retainedMetadataBytes(draft) -
         (previous === undefined ? 0 : retainedMetadataBytes(previous));
     if (!retainEvent(state, bytes))
@@ -294,14 +308,10 @@ const waitForCapture = async (connection, observationMs, signal) => {
 const retainedMetadataBytes = (value) => {
     const strings = "rawUrl" in value
         ? [value.rawUrl, value.rawUrl, value.executionContextKey, value.cdpHash]
-        : [value.contextKey, value.origin];
+        : [value.contextKey, value.name, value.origin];
     return (RETAINED_OBJECT_OVERHEAD_BYTES +
         strings.reduce((total, text) => total + (text?.length ?? 0) * 2, 0));
 };
-const nonnegativeInteger = (value) => {
-    const parsed = numberValue(value);
-    return parsed === undefined ? 0 : Math.max(0, Math.trunc(parsed));
-};
 const contextKey = (value) => {
     const identifier = numberValue(value);
     return identifier !== undefined && Number.isSafeInteger(identifier)

package/dist/javascript/recovery/WakaruCommand.js

@@ -10,6 +10,7 @@ import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../pro
 import { checkRecoveryDeadline, inventoryRecoveryFiles, fingerprintRecoveryFile, recoveryFailureMessage, } from "./RecoveryFiles.js";
 import { RECOVERY_LIMITS } from "./WakaruRelease.js";
 const OPERATION = "recover_javascript_sources";
+const WAKARU_REQUIREMENT = "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA";
 /** Resolve and fingerprint explicitly configured tools; acquire nothing at startup. */
 export const resolveWakaruCommand = async (environment) => {
     const configured = environment.REA_WAKARU_COMMAND;
@@ -17,7 +18,7 @@ export const resolveWakaruCommand = async (environment) => {
         process.arch !== "x64" ||
         configured === undefined ||
         !isAbsolute(configured))
-        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA");
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, WAKARU_REQUIREMENT, { userMessage: WAKARU_REQUIREMENT });
     try {
         const command = await realpath(configured);
         await access(command, constants.R_OK | constants.X_OK);
@@ -29,7 +30,11 @@ export const resolveWakaruCommand = async (environment) => {
         return { command, limiter, ...fingerprint };
     }
     catch (cause) {
-        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`, { cause });
+        const reason = `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`;
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, reason, {
+            cause,
+            userMessage: reason,
+        });
     }
 };
 /** Run one bounded command and verify cleanup before consuming its output. */

package/dist/javascript/recovery/WakaruExecution.js

@@ -30,8 +30,11 @@ const executeWakaruRecovery = async (context) => {
         arguments: ["--version"],
     });
     if (version.exit_code !== 0 ||
-        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`)
-        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}; stderr: ${version.stderr}`);
+        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`) {
+        // The message names the mismatch; the reason also keeps the tool's stderr.
+        const mismatch = `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}`;
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `${mismatch}; stderr: ${version.stderr}`, { userMessage: `${mismatch}.` });
+    }
     const run = await runWakaruCommand({
         ...commandContext,
         staging,

package/dist/main/shutdown.js

@@ -1,16 +1,20 @@
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { MCP_SHUTDOWN_FAILED } from "./messages.js";
 export const createShutdown = (input) => {
-    const { handle, session, unregisterReload, dependencies, serverLogger } = input;
+    const { handle, session, dependencies, serverLogger } = input;
     let shutdownPromise;
     let unregisterShutdown = () => undefined;
     const shutdown = async () => {
         shutdownPromise ??= (async () => {
-            unregisterReload();
             unregisterShutdown();
             const results = await Promise.allSettled([
                 handle.close(),
                 input.closeAndroid?.(),
-                session.close({ retainProviderDocuments: true }),
+                session.close({ retainProviderDocuments: true }).then((closed) => {
+                    if (!closed.ok)
+                        throw closed.error;
+                }),
             ]);
             for (const result of results)
                 if (result.status === "rejected")
@@ -24,12 +28,16 @@ export const createShutdown = (input) => {
             dependencies.setExitCode(1);
             serverLogger.error(MCP_SHUTDOWN_FAILED);
             dependencies.writeStderr(`${MCP_SHUTDOWN_FAILED}\n`);
+            if (cause instanceof AnalysisError)
+                dependencies.writeStderr(`${projectAnalysisError(cause).message}\n`);
         });
     };
     unregisterShutdown = dependencies.registerShutdown(requestShutdown);
     return { shutdown, request: requestShutdown };
 };
 const describeShutdownFailure = (cause) => {
+    if (cause instanceof AnalysisError)
+        return { analysis_error: projectAnalysisError(cause) };
     if (cause instanceof Error) {
         const code = "code" in cause ? cause.code : undefined;
         return {

package/dist/main/startup.js

@@ -7,8 +7,15 @@ export const openInitialTarget = async (session, config, serverLogger, writeStde
     });
     if (opened.ok)
         return { ok: true };
-    await session.close();
-    serverLogger.error({ errorTag: opened.error._tag }, "Initial target failed to open");
+    const closed = await session.close();
+    serverLogger.error({
+        error: projectAnalysisError(opened.error),
+        ...(closed.ok
+            ? {}
+            : { cleanup_error: projectAnalysisError(closed.error) }),
+    }, "Initial target failed to open");
     writeStderr(`${projectAnalysisError(opened.error).message}\n`);
+    if (!closed.ok)
+        writeStderr(`${projectAnalysisError(closed.error).message}\n`);
     return { ok: false, exitCode: 1 };
 };

package/dist/main/transport.js

@@ -1,5 +1,6 @@
 import { createAndroidAnalysisProvider } from "../composition/android.js";
 import { createServer } from "../server/createServer.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { MCP_CONNECTION_LOST, MCP_CONNECTION_START_FAILED, } from "./messages.js";
 export const startMcpTransport = async (dependencies, session, serverContext) => {
     const { serverLogger } = serverContext;
@@ -26,10 +27,12 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
     try {
         handle = dependencies.serve(() => {
             // The SDK can discard a discovery probe and construct a replacement server.
-            const android = createAndroidAnalysisProvider(dependencies.env);
+            const android = createAndroidAnalysisProvider(serverContext.environment);
             androidProviders.push(android);
             return (dependencies.createServer ?? createServer)(session, session, {
                 logger: serverContext.logger,
+                environment: serverContext.environment,
+                delivery: serverContext.delivery,
                 ...optionalProviders,
                 androidAnalysis: android,
             });
@@ -41,11 +44,28 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
         });
     }
     catch (cause) {
-        await Promise.allSettled([session.close(), closeAndroid()]);
+        const [binaryCleanup, androidCleanup] = await Promise.allSettled([
+            session.close(),
+            closeAndroid(),
+        ]);
         serverLogger.error({
             error: cause instanceof Error ? cause.message : String(cause),
         }, MCP_CONNECTION_START_FAILED);
         dependencies.writeStderr(`${MCP_CONNECTION_START_FAILED}\n`);
+        if (binaryCleanup.status === "fulfilled" && !binaryCleanup.value.ok) {
+            const cleanupError = projectAnalysisError(binaryCleanup.value.error);
+            serverLogger.error({ cleanup_error: cleanupError }, "Binary provider cleanup failed after MCP startup");
+            dependencies.writeStderr(`${cleanupError.message}\n`);
+        }
+        for (const cleanup of [binaryCleanup, androidCleanup]) {
+            if (cleanup.status === "rejected") {
+                const reason = cleanup.reason instanceof Error
+                    ? cleanup.reason.message
+                    : String(cleanup.reason);
+                serverLogger.error({ cleanup_error: reason }, "Provider cleanup rejected after MCP startup");
+                dependencies.writeStderr(`Provider cleanup failed: ${reason}\n`);
+            }
+        }
         return { ok: false };
     }
     return { ok: true, handle, closeAndroid };

package/dist/main.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
+import { snapshotEnvironment } from "./process/snapshotEnvironment.js";
 import { pathToFileURL } from "node:url";
 import { realpathSync } from "node:fs";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { parseConfig } from "./config.js";
+import { parseConfig } from "./config/parseConfig.js";
 import { createBinarySession } from "./composition/binary.js";
 import { createLogger } from "./logger.js";
 import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
 import { SERVER_START_FAILED } from "./main/messages.js";
-import { createRuntimeState } from "./main/state.js";
 import { openInitialTarget } from "./main/startup.js";
 import { startMcpTransport } from "./main/transport.js";
-import { loadOptionalObservationProviders } from "./composition/optionalObservationProviders.js";
-import { registerConfigReload } from "./main/reload.js";
+import { createOptionalObservationFactories, loadOptionalObservationProviders, } from "./composition/optionalObservationProviders.js";
+import { createToolResultDelivery } from "./server/toolResult.js";
 import { createShutdown } from "./main/shutdown.js";
 const runtimeDependencies = () => ({
     env: process.env,
@@ -32,10 +32,6 @@ const runtimeDependencies = () => ({
             process.stdin.off("close", handler);
         };
     },
-    registerReload: (handler) => {
-        process.on("SIGHUP", handler);
-        return () => process.off("SIGHUP", handler);
-    },
 });
 /**
  * Start the long-lived MCP adapter and install idempotent shutdown handlers.
@@ -43,35 +39,32 @@ const runtimeDependencies = () => ({
  * signals close bridge resources without assuming ownership of the Hopper app.
  */
 export const run = async (dependencies = runtimeDependencies()) => {
-    const config = parseConfig(dependencies.env);
+    const environment = snapshotEnvironment(dependencies.env);
+    const config = parseConfig(environment);
     if (!config.ok) {
         dependencies.writeStderr(`${projectAnalysisError(config.error).message}\n`);
         return 1;
     }
     const logger = createLogger("mcp", config.value.logLevel);
     const serverLogger = logger.child({ layer: "server" });
-    const session = createBinarySession(config.value, logger);
+    const session = createBinarySession(config.value, logger, environment);
     const opened = await openInitialTarget(session, config.value, serverLogger, dependencies.writeStderr);
     if (!opened.ok)
         return opened.exitCode;
-    const runtimeState = createRuntimeState(config.value);
     const transport = await startMcpTransport(dependencies, session, {
         logger,
         serverLogger,
-        loadOptionalProviders: dependencies.loadOptionalProviders ?? loadOptionalObservationProviders,
+        environment,
+        delivery: createToolResultDelivery(config.value.mcpMaxResponseBytes),
+        loadOptionalProviders: dependencies.loadOptionalProviders ??
+            (() => loadOptionalObservationProviders(createOptionalObservationFactories(environment))),
     });
     if (!transport.ok)
         return 1;
-    const unregisterReload = registerConfigReload({
-        dependencies,
-        runtimeState,
-        serverLogger,
-    });
     createShutdown({
         handle: transport.handle,
         closeAndroid: transport.closeAndroid,
         session,
-        unregisterReload,
         dependencies,
         serverLogger,
     });

package/dist/native/AppleMachoSelection.js

@@ -182,9 +182,14 @@ const collectFixupCommand = (bytes, { cursor, kind, size }, state) => {
             throw new RangeError("Fixup data exceeds the Mach-O slice");
         return { offset, size: length };
     };
-    if (kind === LC_DYLD_CHAINED_FIXUPS && size >= 16)
+    if (kind === LC_DYLD_CHAINED_FIXUPS) {
+        if (size < 16)
+            throw new RangeError("Truncated chained-fixups command");
         state.chained = range(cursor + 8);
-    else if ((kind === LC_DYLD_INFO || kind === LC_DYLD_INFO_ONLY) && size >= 48)
+    }
+    else if (kind === LC_DYLD_INFO || kind === LC_DYLD_INFO_ONLY) {
+        if (size < 48)
+            throw new RangeError("Truncated dyld-info command");
         for (const [at, stream] of [
             [cursor + 16, "bind"],
             [cursor + 24, "weak"],
@@ -194,11 +199,16 @@ const collectFixupCommand = (bytes, { cursor, kind, size }, state) => {
             if (bound.size > 0)
                 state.binds.push({ ...bound, stream });
         }
-    else if (DYLIB_COMMANDS.includes(kind) && size >= 24) {
+    }
+    else if (DYLIB_COMMANDS.includes(kind)) {
+        if (size < 24)
+            throw new RangeError("Truncated dylib command");
         const nameOffset = bytes.readUInt32LE(cursor + 8);
+        if (nameOffset < 24 || nameOffset >= size)
+            throw new RangeError("Dylib install name is outside its load command");
         const end = bytes.indexOf(0, cursor + nameOffset);
-        state.dylibs.push(nameOffset >= size || end < 0 || end > cursor + size
-            ? ""
-            : bytes.toString("utf8", cursor + nameOffset, end));
+        if (end < 0 || end >= cursor + size)
+            throw new RangeError("Unterminated dylib install name");
+        state.dylibs.push(bytes.toString("utf8", cursor + nameOffset, end));
     }
 };

package/dist/native/CommandRunner.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { realpath } from "node:fs/promises";
@@ -28,8 +29,10 @@ export class NativeCommandFailure extends Error {
 /** Run allowlisted Xcode tools directly without a shell. */
 export class XcrunCommandRunner {
     resolveTool;
-    constructor(resolveTool = (tool, signal) => resolveXcrunTool(tool, signal)) {
+    environment;
+    constructor(environment, resolveTool = (tool, signal) => resolveXcrunTool(tool, this.environment, signal)) {
         this.resolveTool = resolveTool;
+        this.environment = snapshotEnvironment(environment);
     }
     run(tool, arguments_, options) {
         if (!ALLOWED_TOOLS.has(tool))
@@ -37,7 +40,7 @@ export class XcrunCommandRunner {
         return this.resolveTool(tool, options.signal).then(async (resolved) => {
             if (!resolved.ok)
                 return resolved;
-            const captured = await captureProcess(resolved.value.path, arguments_, tool, options);
+            const captured = await captureProcess(resolved.value.path, arguments_, tool, options, this.environment);
             return captured.ok
                 ? ok({
                     ...captured.value,
@@ -66,8 +69,8 @@ const ALLOWED_TOOLS = new Set([
     "vtool",
 ]);
 /** Locate an Xcode tool through `xcrun --find` and sample its executable digest. */
-export const resolveXcrunTool = async (tool, signal) => {
-    const found = await captureProcess("/usr/bin/xcrun", ["--find", tool], "xcrun", signal === undefined ? {} : { signal });
+export const resolveXcrunTool = async (tool, environment, signal) => {
+    const found = await captureProcess("/usr/bin/xcrun", ["--find", tool], "xcrun", signal === undefined ? {} : { signal }, environment);
     if (!found.ok) {
         return err(new NativeCommandFailure(tool, found.error.reason === "nonzero-exit" ||
             found.error.reason === "unavailable"
@@ -99,7 +102,7 @@ const failureCapture = (capture, truncated) => ({
     signal: capture.signal,
     truncated,
 });
-const captureProcess = async (executable, arguments_, tool, options) => {
+const captureProcess = async (executable, arguments_, tool, options, environment) => {
     const runId = `rea-native-command-${randomUUID()}`;
     try {
         const snapshot = await runOwnedCommand({
@@ -107,11 +110,10 @@ const captureProcess = async (executable, arguments_, tool, options) => {
             arguments: [...arguments_],
             runId,
             env: {
-                PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
                 LC_ALL: "C",
                 LANG: "C",
             },
-            hostEnvironment: {},
+            hostEnvironment: environment,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         }, {
             timeoutMs: NATIVE_COMMAND_TIMEOUT_MS,

package/dist/native/LldbCallTracer.js

@@ -1,3 +1,4 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { randomUUID } from "node:crypto";
 import { open, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -18,6 +19,7 @@ import { resolveXcrunTool } from "./CommandRunner.js";
 import { readLldbObservationJournal, readBoundedPrefix, readPartialCapture, projectLldbPartialObservation, } from "./LldbRetainedObservations.js";
 const OPERATION = "observe_native_calls";
 const PROVIDER = "native-macos";
+const LLDB_REQUIREMENT = "LLDB from Xcode or the Command Line Tools is not available";
 /** Captured target output kept per stream; the rest is counted, not stored. */
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 /** LLDB startup, symbol loading and teardown beyond the observation window. */
@@ -90,16 +92,18 @@ const ATTACH_REMEDIATION = "Allow debugging for this user (Developer Tools acces
 export class LldbCallTracer {
     launch;
     resolveTool;
-    constructor(launch = runLldb, resolveTool = resolveXcrunTool) {
+    environment;
+    constructor(environment, launch = runLldb, resolveTool = (tool, signal) => resolveXcrunTool(tool, this.environment, signal)) {
         this.launch = launch;
         this.resolveTool = resolveTool;
+        this.environment = snapshotEnvironment(environment);
     }
     async trace(request, signal) {
         const lldb = await this.resolveTool("lldb", signal);
         if (!lldb.ok)
             return err(lldb.error.reason === "cancelled"
                 ? new AnalysisCancelledError(OPERATION)
-                : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, "LLDB from Xcode or the Command Line Tools is not available"));
+                : new AnalysisCapabilityUnavailableError(PROVIDER, OPERATION, LLDB_REQUIREMENT, { userMessage: LLDB_REQUIREMENT }));
         const root = await PrivateRuntimeRoot.create({ prefix: "rea-lldb-" });
         try {
             return await this.#run(lldb.value, root.path, request, signal);
@@ -158,6 +162,7 @@ export class LldbCallTracer {
             deadlineMs: input.duration_ms + DEADLINE_GRACE_MS,
             pidPath: paths.pid,
             identityAckPath: paths.identityAck,
+            environment: this.environment,
             ...(signal === undefined ? {} : { signal }),
         });
         const output = exited.kind === "exited"
@@ -402,6 +407,7 @@ const runLldb = async (executable, arguments_, options) => {
             runId: randomUUID(),
             expectedCommand: executable,
             signal: deadline.signal,
+            hostEnvironment: options.environment,
         });
         supervisor = new ProviderProcessSupervisor({
             ...launched,

package/dist/native/NativeMacOSProvider.js

@@ -1,5 +1,5 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { NATIVE_MACOS_PROVIDER_IDENTITY as IDENTITY, nativeMacOSCapabilities, } from "./NativeMacOSProviderMetadata.js";
-export { NATIVE_MACOS_PROVIDER_IDENTITY } from "./NativeMacOSProviderMetadata.js";
 import { inspectAppleDispatchMetadata } from "./AppleDispatchMetadata.js";
 import { observeNativeUi } from "./NativeUiObservation.js";
 import { LldbCallTracer } from "./LldbCallTracer.js";
@@ -9,6 +9,8 @@ import { open, realpath, stat } from "node:fs/promises";
 import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
 import { NATIVE_TOOL_CONTRACTS, } from "../contracts/native/nativeToolContracts.js";
+import { toolContract } from "../contracts/toolContracts.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -29,9 +31,11 @@ export class NativeMacOSProvider {
     runner;
     tracer;
     #capabilities;
-    constructor(runner = new XcrunCommandRunner(), platform = process.platform, tracer = new LldbCallTracer()) {
+    #environment;
+    constructor(environment, runner = new XcrunCommandRunner(environment), platform = process.platform, tracer = new LldbCallTracer(environment)) {
         this.runner = runner;
         this.tracer = tracer;
+        this.#environment = snapshotEnvironment(environment, platform);
         this.#capabilities = nativeMacOSCapabilities(platform);
     }
     identity() {
@@ -41,17 +45,19 @@ export class NativeMacOSProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new NativeMacOSClient(target, this.runner, this.tracer);
+        return new NativeMacOSClient(target, this.runner, this.tracer, this.#environment);
     }
 }
 class NativeMacOSClient {
     target;
     runner;
     tracer;
-    constructor(target, runner, tracer) {
+    environment;
+    constructor(target, runner, tracer, environment) {
         this.target = target;
         this.runner = runner;
         this.tracer = tracer;
+        this.environment = environment;
     }
     async execute(operation, parameters, options) {
         if (options?.signal?.aborted === true)
@@ -59,16 +65,15 @@ class NativeMacOSClient {
         if (operation === "health")
             return ok(createAnalysisExecution(null, IDENTITY));
         if (operation === "inspect_native_dispatch_metadata") {
+            const input = toolContract(operation).inputSchema.safeParse(parameters);
+            if (!input.success)
+                return err(analysisInputErrorFromIssues(operation, input.error.issues, parameters, {
+                    cause: input.error,
+                }));
             if (this.target.kind !== "executable" || this.target.format !== "mach-o")
                 return err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, "Binary Apple metadata requires Mach-O; other providers can report symbol-only metadata"));
             try {
-                const maxRecords = z
-                    .number()
-                    .int()
-                    .min(1)
-                    .max(20000)
-                    .parse(parameters.max_records ?? 5000);
-                const result = await inspectAppleDispatchMetadata(this.target, maxRecords, options?.signal);
+                const result = await inspectAppleDispatchMetadata(this.target, input.data.max_records, options?.signal);
                 return ok(createAnalysisExecution(result, result.provider, {
                     locations: [{ kind: "artifact-path", path: this.target.path }],
                     limitations: result.result.coverage.flatMap(({ reason }) => reason === null ? [] : [reason]),
@@ -102,6 +107,7 @@ class NativeMacOSClient {
         if (operation === "observe_native_ui" ||
             operation === "capture_native_ui_scenario") {
             const result = await observeNativeUi(this.target, operation, parameters, {
+                environment: this.environment,
                 signal: options?.signal,
             });
             return result.ok
@@ -127,7 +133,7 @@ class NativeMacOSClient {
         }
     }
     close() {
-        return Promise.resolve();
+        return Promise.resolve(ok(null));
     }
     #dispatch(operation, parameters, signal) {
         switch (operation) {
@@ -424,8 +430,10 @@ const translateCommandFailure = (operation, failure) => {
         ...(capturedOutput === undefined ? {} : { capturedOutput }),
         ...(cleanup === undefined ? {} : { cleanup }),
     };
-    if (failure.reason === "unavailable")
-        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `${failure.tool} is unavailable through xcrun.`, errorOptions);
+    if (failure.reason === "unavailable") {
+        const reason = `${failure.tool} is unavailable through xcrun.`;
+        return new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, reason, { ...errorOptions, userMessage: reason });
+    }
     if (failure.reason === "cancelled")
         return new AnalysisCancelledError(operation, errorOptions);
     if (failure.reason === "timeout")
@@ -513,8 +521,10 @@ const parseEntitlements = (output) => {
  */
 const unreadablePlist = (path, requested, reason) => {
     const sentence = reason.endsWith(".") ? reason : `${reason}.`;
+    // Name the default that is missing and the selection that still works.
+    const missingDefault = `The target has no readable Contents/Info.plist at ${path}: ${sentence} Select another plist in the target with the path input (CLI: --relative-path).`;
     return requested === undefined
-        ? new AnalysisCapabilityUnavailableError(IDENTITY.id, "inspect_plist", `The target has no readable Contents/Info.plist at ${path}: ${sentence} Pass path to inspect another plist.`)
+        ? new AnalysisCapabilityUnavailableError(IDENTITY.id, "inspect_plist", missingDefault, { userMessage: missingDefault })
         : new AnalysisInputError("inspect_plist", undefined, [
             {
                 path: ["path"],