rea-agents 2.1.0 → 2.3.0

package/dist/ghidra/GhidraClient.js

@@ -6,6 +6,7 @@ import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { GHIDRA_MAX_LINE_BYTES, GHIDRA_MAX_QUEUED_REQUESTS, GHIDRA_REQUEST_TIMEOUT_MS, GHIDRA_STARTUP_TIMEOUT_MS, } from "./GhidraDefaults.js";
 import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
@@ -33,6 +34,7 @@ export class GhidraClient {
     #snapshotPath;
     #token;
     #runId;
+    #lineage = new ProviderRunLineage();
     #nextId = 1;
     #closing = false;
     #processSnapshot;
@@ -145,6 +147,10 @@ export class GhidraClient {
     diagnostics() {
         return structuredClone(this.#diagnostics());
     }
+    /** Latest token-verified launcher lineage for the active run. */
+    runtimeLineage() {
+        return this.#lineage.snapshot();
+    }
     async #start(signal) {
         if (signal.aborted)
             return err(this.#failure("cancelled", "Ghidra startup was cancelled"));
@@ -188,7 +194,8 @@ export class GhidraClient {
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
         this.#token = randomBytes(32).toString("hex");
-        this.#runId = randomUUID();
+        this.#lineage.reset();
+        this.#runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
             .launch({
             runtimeRoot: this.#runtimeRoot.path,
@@ -221,7 +228,7 @@ export class GhidraClient {
             await this.#cleanup();
             return err(failure);
         }
-        return completeGhidraStartupHandshake({
+        const completed = await completeGhidraStartupHandshake({
             deadline,
             request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
             parseSessionInfo: (value) => this.#parseSessionInfo(value),
@@ -229,6 +236,9 @@ export class GhidraClient {
             failure: this.#failure,
             startupTimeoutMs: this.#options.startupTimeoutMs,
         });
+        if (completed.ok)
+            await this.#lineage.observe(this.#launch);
+        return completed;
     }
     async #connect(endpoint, deadline) {
         const connected = await connectGhidraSocket({
@@ -373,6 +383,7 @@ export class GhidraClient {
             transport: this.#options.transport,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
+            ...(this.#runId === undefined ? {} : { runId: this.#runId }),
             ...(this.#runtimeRoot === undefined
                 ? {}
                 : { runtimeRoot: this.#runtimeRoot.path }),

package/dist/ghidra/GhidraDiagnostics.js

@@ -14,6 +14,7 @@ export const createGhidraDiagnostics = (options) => {
         transport: options.transport,
         provider_version: options.providerVersion,
         profile_digest: options.profileDigest,
+        ...(options.runId === undefined ? {} : { run_id: options.runId }),
         ...(options.runtimeRoot === undefined
             ? {}
             : {

package/dist/ghidra/GhidraLauncher.js

@@ -91,9 +91,7 @@ export class GhidraHeadlessLauncher {
             }
             const spawned = started;
             return ok({
-                process: spawned.process,
-                ownsProcessLifetime: true,
-                cleanup: () => cleanupStartedProcess(spawned, platform),
+                ...ownedGhidraProcess(spawned, platform),
                 projectRoot: paths.projectRoot,
                 ghidraLogPath: paths.ghidraLogPath,
                 scriptLogPath: paths.scriptLogPath,
@@ -108,6 +106,12 @@ export class GhidraHeadlessLauncher {
         }
     }
 }
+const ownedGhidraProcess = (spawned, platform) => ({
+    process: spawned.process,
+    ownsProcessLifetime: true,
+    ownership: spawned.ownership,
+    cleanup: () => cleanupStartedProcess(spawned, platform),
+});
 /** Build a direct POSIX launch or a conservatively quoted Windows batch call. */
 export const ghidraHeadlessCommand = (options) => {
     if (options.platform !== "win32")

package/dist/ghidra/GhidraProvider.js

@@ -95,7 +95,7 @@ export class GhidraProvider {
     resolveAnalysisProfile(target, options) {
         return resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, this.#inspectInstallation(), options?.signal);
     }
-    createClient(target, profile) {
+    createClient(target, profile, context) {
         const installation = this.#inspectInstallation();
         const prerequisites = ghidraClientPrerequisites(target, profile, installation);
         if (!prerequisites.ok)
@@ -118,6 +118,7 @@ export class GhidraProvider {
                 : "unix-socket",
             providerVersion: prerequisites.value.providerVersion,
             profileDigest: committedProfile.digest,
+            ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "ghidra-bridge" }),
         });
         return {
@@ -160,6 +161,12 @@ export class GhidraProvider {
                     limitations: [...limitationsFor(operation), ...providerLimitations],
                 }));
             },
+            runtimeLineageSnapshots: () => {
+                const observation = client.runtimeLineage?.() ?? null;
+                return observation === null
+                    ? []
+                    : [{ provider: committedProfile.provider, observation }];
+            },
             close: () => client.close(),
         };
     }

package/dist/hopper/BridgeLauncher.js

@@ -2,11 +2,12 @@ import { execFile } from "node:child_process";
 import { chmod, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import { promisify } from "node:util";
-import { HopperCancelledError, HopperStartError } from "../domain/errors.js";
+import { HopperCancelledError, HopperProcessError, HopperStartError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
+import { selectLinuxPrivateDisplayStrategy, } from "./LinuxPrivateDisplayProbe.js";
 import writeFileAtomic from "write-file-atomic";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
@@ -26,8 +27,10 @@ const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
  */
 export class HopperApplicationLauncher {
     options;
-    constructor(options) {
+    dependencies;
+    constructor(options, dependencies = {}) {
         this.options = options;
+        this.dependencies = dependencies;
     }
     async launch(session, options = {}) {
         const bootstrapPath = `${session.directory}/bootstrap.py`;
@@ -60,10 +63,13 @@ export class HopperApplicationLauncher {
         try {
             if (options.signal?.aborted === true)
                 return err(new HopperCancelledError());
+            const display = await this.#privateDisplay(options.signal);
+            if (!display.ok)
+                return err(display.error);
             const prepared = await prepareHopperApplication(this.options.launcherPath, options.signal);
             if (!prepared)
                 return err(new HopperCancelledError());
-            const linuxDemo = linuxDemoLaunch(this.options, session, args);
+            const linuxDemo = linuxDemoLaunch(this.options, session, args, display.strategy);
             const ownershipCommand = linuxDemo?.ownershipCommand ?? this.options.launcherPath;
             const started = await spawnOwnedProviderProcess({
                 command: linuxDemo?.command ?? this.options.launcherPath,
@@ -92,6 +98,7 @@ export class HopperApplicationLauncher {
             return ok({
                 process: child,
                 ownsProcessLifetime: true,
+                ownership: started.ownership,
                 shutdownByCleanup: ownsProcessLifetime,
                 cleanup: () => cleanupOwnedProcessGroup(started.ownership),
             });
@@ -100,23 +107,58 @@ export class HopperApplicationLauncher {
             return err(hopperLaunchFailure(cause, options.signal));
         }
     }
+    async #privateDisplay(signal) {
+        if (!usesLinuxDemo(this.options))
+            return { ok: true, strategy: undefined };
+        const selection = await (this.dependencies.selectPrivateDisplay ??
+            selectLinuxPrivateDisplayStrategy)({
+            helperPath: this.options.demoHelperPath,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (signal?.aborted === true)
+            return { ok: false, error: new HopperCancelledError() };
+        return selection.ok
+            ? { ok: true, strategy: selection.strategy }
+            : {
+                ok: false,
+                error: new HopperProcessError(selection.exitCode, selection.diagnostic),
+            };
+    }
 }
-const linuxDemoLaunch = (options, session, hopperArgs) => {
+export const linuxDemoLaunch = (options, session, hopperArgs, strategy) => {
     if (!usesLinuxDemo(options) || options.demoHelperPath === undefined)
         return undefined;
+    const helperArguments = [
+        options.demoHelperPath,
+        "--strategy",
+        strategy ?? "direct",
+        ...(strategy === "user-mount-namespace" ? ["--mount-private-x11"] : []),
+        "--hopper",
+        options.launcherPath,
+        "--socket",
+        session.socketPath,
+        "--",
+        options.launcherPath,
+        ...hopperArgs,
+    ];
+    if (strategy === "user-mount-namespace")
+        return {
+            command: "/usr/bin/unshare",
+            ownershipCommand: "/usr/bin/python3",
+            args: [
+                "--user",
+                "--map-root-user",
+                "--mount",
+                "--propagation",
+                "private",
+                "/usr/bin/python3",
+                ...helperArguments,
+            ],
+        };
     return {
         command: "/usr/bin/python3",
         ownershipCommand: "/usr/bin/python3",
-        args: [
-            options.demoHelperPath,
-            "--hopper",
-            options.launcherPath,
-            "--socket",
-            session.socketPath,
-            "--",
-            options.launcherPath,
-            ...hopperArgs,
-        ],
+        args: helperArguments,
     };
 };
 const hopperLaunchFailure = (cause, signal) => signal?.aborted === true

package/dist/hopper/HopperClient.js

@@ -8,13 +8,17 @@ import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
+import { createOwnedHopperShutdownDiagnostic, providerCleanupFailure, } from "./HopperDiagnostics.js";
 import { isHopperCleanupRequired, isHopperShutdownAcknowledgement, parseHopperServerInfo, } from "./HopperSessionValues.js";
 import { connectHopperSocketOnce } from "./HopperSocketConnection.js";
+import { hopperLauncherFailureDiagnostic } from "./HopperProcessDiagnostic.js";
 import { parseResponseLine, responseResult } from "./protocol.js";
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
+/** Safe launcher telemetry; stderr content is intentionally never exposed. */
 /**
  * Owns one authenticated NDJSON-over-Unix-socket bridge session.
  *
@@ -32,10 +36,12 @@ export class HopperClient {
     #process;
     #runtimeRoot;
     #token;
+    #lineage = new ProviderRunLineage();
     #nextId = 1;
     #buffer = "";
     #closing = false;
     #launcherExitCode;
+    #launcherFailureDiagnostic;
     #startupController;
     #startPromise;
     #closePromise;
@@ -57,6 +63,10 @@ export class HopperClient {
             startupTimeoutMs: options.startupTimeoutMs ?? 120_000,
         };
     }
+    /** Latest token-verified launcher lineage for the active run. */
+    runtimeLineage() {
+        return this.#lineage.snapshot();
+    }
     /** Launch the bridge once and complete its authenticated health handshake. */
     start(signal) {
         if (this.#closePromise !== undefined) {
@@ -124,8 +134,10 @@ export class HopperClient {
         }
         const socketPath = join(this.#runtimeRoot.path, "bridge.sock");
         this.#token = randomBytes(32).toString("hex");
+        this.#lineage.reset();
         this.#launcherExitCode = undefined;
-        const runId = randomUUID();
+        this.#launcherFailureDiagnostic = undefined;
+        const runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
             .launch({
             directory: this.#runtimeRoot.path,
@@ -163,7 +175,9 @@ export class HopperClient {
                 : health;
         }
         const parsed = parseHopperServerInfo(health.value, runId);
-        if (!parsed.ok)
+        if (parsed.ok)
+            await this.#lineage.observe(this.#launch);
+        else
             await this.#cleanup();
         return parsed;
     }
@@ -228,6 +242,9 @@ export class HopperClient {
             this.#socket = undefined;
             if (this.#process !== undefined) {
                 const stopped = await this.#process.stop(cleanupResult === undefined ? {} : { cleanupResult });
+                const diagnostic = createOwnedHopperShutdownDiagnostic(this.#process.launch, stopped, cleanupResult);
+                this.#options.onDiagnostic?.(diagnostic);
+                this.#logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
                 if (stopped.status === "incomplete")
                     this.#logger.warn({ reason: stopped.reason }, "Owned launcher cleanup failed closed");
             }
@@ -239,6 +256,7 @@ export class HopperClient {
             this.#token = undefined;
             this.#buffer = "";
             this.#launcherExitCode = undefined;
+            this.#launcherFailureDiagnostic = undefined;
         }
         finally {
             this.#closing = false;
@@ -257,7 +275,7 @@ export class HopperClient {
                 return err(new HopperProcessError(null));
             if (this.#launcherExitCode !== undefined &&
                 hopperStartupFailure(this.#launcherExitCode) !== undefined)
-                return err(new HopperProcessError(this.#launcherExitCode));
+                return err(new HopperProcessError(this.#launcherExitCode, this.#launcherFailureDiagnostic));
             try {
                 await access(socketPath);
             }
@@ -338,12 +356,13 @@ export class HopperClient {
         if (event.type !== "exit")
             return;
         this.#launcherExitCode = event.code;
+        this.#launcherFailureDiagnostic = hopperLauncherFailureDiagnostic(event);
         this.#options.onDiagnostic?.({
             type: "launcher-exit",
             code: event.code,
         });
         if (launch.ownsProcessLifetime && !this.#closing)
-            this.#failAll(new HopperProcessError(event.code));
+            this.#failAll(new HopperProcessError(event.code, this.#launcherFailureDiagnostic));
     }
     #onData(chunk) {
         this.#buffer += chunk;
@@ -389,9 +408,3 @@ const isAborted = (signal) => signal?.aborted === true;
 const startupInterruption = (deadline) => deadline.cancelled
     ? new HopperCancelledError()
     : new HopperTimeoutError(deadline.timeoutMs);
-const providerCleanupFailure = (cause) => ({
-    cleaned: false,
-    reason: cause instanceof Error
-        ? `owned provider cleanup failed: ${cause.message}`
-        : "owned provider cleanup failed",
-});

package/dist/hopper/HopperDiagnostics.js

@@ -0,0 +1,14 @@
+/** Retain actionable ownership coordinates without exposing the run token. */
+export const createOwnedHopperShutdownDiagnostic = (launch, stopped, cleanup) => ({
+    type: "owned-shutdown",
+    status: stopped.status,
+    launcher_pid: launch.ownership?.leaderPid ?? launch.process.pid ?? null,
+    process_group_id: launch.ownership?.processGroupId ?? null,
+    cleanup_signaled: cleanup?.cleaned === true ? cleanup.signaled : null,
+    reason: stopped.status === "incomplete" ? stopped.reason : null,
+});
+/** Convert an unexpected cleanup rejection without exposing a stack or token. */
+export const providerCleanupFailure = (_cause) => ({
+    cleaned: false,
+    reason: "owned provider cleanup failed",
+});

package/dist/hopper/HopperProcessDiagnostic.js

@@ -0,0 +1,14 @@
+import { hopperStartupFailure, } from "../domain/errors.js";
+import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
+/** Extract only a matching, versioned Linux adapter failure record. */
+export const hopperLauncherFailureDiagnostic = (event) => {
+    const parsed = parseLinuxPrivateDisplayDiagnostic(event.snapshot.stderr.text, event.snapshot.stderr.truncated);
+    if (!parsed.ok)
+        return undefined;
+    const expected = hopperStartupFailure(event.code)?.code;
+    return parsed.value.operation === "launch" &&
+        parsed.value.status === "error" &&
+        parsed.value.failure_code === expected
+        ? parsed.value
+        : undefined;
+};

package/dist/hopper/HopperProvider.js

@@ -147,7 +147,7 @@ export class HopperProvider {
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
         });
     }
-    createClient(target, profile) {
+    createClient(target, profile, context) {
         if (target.kind !== "executable" && target.kind !== "database")
             return {
                 execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`))),
@@ -176,6 +176,7 @@ export class HopperProvider {
                     }
                     : { launchMode: "native" }),
             }),
+            ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "bridge" }),
         });
         return {
@@ -193,6 +194,12 @@ export class HopperProvider {
                     }
                     : result;
             },
+            runtimeLineageSnapshots: () => {
+                const observation = client.runtimeLineage();
+                return observation === null
+                    ? []
+                    : [{ provider: executionProvider, observation }];
+            },
             close: () => client.close(),
         };
     }

package/dist/hopper/LinuxPrivateDisplayDiagnostic.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { isHopperStartupFailureCode, } from "../domain/hopperStartupFailure.js";
+export const LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC_V1=";
+const diagnosticSchema = z
+    .object({
+    schema_version: z.literal(1),
+    component: z.literal("hopper_private_display"),
+    operation: z.enum(["probe", "launch"]),
+    status: z.enum(["ready", "error"]),
+    failure_code: z.string().max(64).nullable(),
+    reason: z
+        .string()
+        .regex(/^[a-z0-9_]+$/u)
+        .max(64),
+    socket_directory: z.literal("/tmp/.X11-unix"),
+    socket_directory_mode: z
+        .string()
+        .regex(/^[0-7]{4}$/u)
+        .nullable(),
+    mount_read_only: z.boolean().nullable(),
+    effective_socket_directory_mode: z
+        .string()
+        .regex(/^[0-7]{4}$/u)
+        .nullable(),
+    effective_mount_read_only: z.boolean().nullable(),
+    wsl: z.boolean(),
+    strategy: z.enum(["direct", "user-mount-namespace", "unavailable"]),
+    fallback_reason: z
+        .string()
+        .regex(/^[a-z0-9_]+$/u)
+        .max(64)
+        .nullable(),
+    xvfb_stderr_bytes: z.number().int().nonnegative().safe(),
+    xvfb_stderr_truncated: z.boolean(),
+})
+    .strict();
+/** Parse exactly one bounded, versioned helper diagnostic from stderr. */
+export const parseLinuxPrivateDisplayDiagnostic = (stderr, truncated) => {
+    if (truncated)
+        return { ok: false, reason: "diagnostic_truncated" };
+    const records = stderr
+        .split("\n")
+        .filter((line) => line.startsWith(LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX));
+    if (records.length === 0)
+        return { ok: false, reason: "diagnostic_missing" };
+    if (records.length !== 1)
+        return { ok: false, reason: "diagnostic_multiple" };
+    const record = records[0];
+    if (record === undefined)
+        return { ok: false, reason: "diagnostic_missing" };
+    try {
+        const parsed = diagnosticSchema.safeParse(JSON.parse(record.slice(LINUX_PRIVATE_DISPLAY_DIAGNOSTIC_PREFIX.length)));
+        if (!parsed.success)
+            return { ok: false, reason: "diagnostic_malformed" };
+        const code = parsed.data.failure_code;
+        if (code !== null && !isHopperStartupFailureCode(code))
+            return { ok: false, reason: "diagnostic_malformed" };
+        if ((parsed.data.status === "ready" && code !== null) ||
+            (parsed.data.status === "error" && code === null))
+            return { ok: false, reason: "diagnostic_malformed" };
+        return {
+            ok: true,
+            value: {
+                ...parsed.data,
+                failure_code: code,
+            },
+        };
+    }
+    catch {
+        return { ok: false, reason: "diagnostic_malformed" };
+    }
+};