rea-agents 5.0.0 → 6.0.0

package/dist/native/pwntools/PwntoolsDecoder.js

@@ -0,0 +1,203 @@
+import { pwntoolsDecoderFailure, pwntoolsUnavailable, capturedPwntoolsOutput, } from "./PwntoolsFailures.js";
+import { randomUUID } from "node:crypto";
+import { access, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { err, ok } from "../../domain/result.js";
+import { runOwnedCommand } from "../../process/OwnedCommand.js";
+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
+import { pwntoolsResourceLimitsSchema, readPwntoolsFailureEvidence, } from "./PwntoolsResourceLimits.js";
+import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
+import { PWNTOOLS_PROVIDER_IDENTITY, PWNTOOLS_LIMITS, } from "./PwntoolsRelease.js";
+/** Thin owned-process adapter; all ELF parsing and heuristics come from unchanged upstream code. */
+export class PwntoolsDecoder {
+    profile;
+    environment;
+    launcher;
+    createRuntime;
+    identity;
+    constructor(profile, environment, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-artifact-decoder-" })) {
+        this.profile = profile;
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+        this.identity = profile.identity;
+    }
+    /** Snapshot one explicit artifact and return complete static observations without launching the selected object as a host process. */
+    async inspect(input, options) {
+        const OPERATION = this.profile.operation;
+        const context = { operation: OPERATION, providerId: this.identity.id };
+        const replySchema = z.discriminatedUnion("ok", [
+            z.strictObject({
+                ok: z.literal(true),
+                profile: z.literal(PWNTOOLS_PROVIDER_IDENTITY.version),
+                value: this.profile.payloadSchema,
+            }),
+            z.strictObject({
+                ok: z.literal(false),
+                reason: z.enum([
+                    "format",
+                    "unsupported",
+                    "unsupported-target",
+                    "unavailable",
+                    "resource-limit",
+                    "output-limit",
+                    "decoder",
+                ]),
+                message: z.string(),
+                reported_limits: pwntoolsResourceLimitsSchema.nullable().optional(),
+            }),
+        ]);
+        let root;
+        let result;
+        let phase = "configuration";
+        const executablePath = this.environment.REA_PWNTOOLS_PYTHON ?? "";
+        let selectedPath = executablePath;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION);
+            if (process.platform !== "linux" || process.arch !== "x64")
+                throw new AnalysisCapabilityUnavailableError(this.identity.id, OPERATION, "The initial real-verified pwntools artifact profile supports Linux x64 only.");
+            if (!isAbsolute(selectedPath))
+                throw pwntoolsUnavailable("Set REA_PWNTOOLS_PYTHON to an absolute caller-supplied Python executable with pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2; REA never installs Python or packages.", selectedPath, undefined, undefined, context);
+            await access(selectedPath, constants.X_OK);
+            if (!(await stat(selectedPath)).isFile())
+                throw pwntoolsUnavailable("Selected Python executable must be a regular executable file, not a directory: " +
+                    selectedPath, selectedPath, undefined, undefined, context);
+            phase = "artifact-read";
+            selectedPath = input.path;
+            const snapshot = await readStableArtifact(input.path, PWNTOOLS_LIMITS.inputBytes, options?.signal);
+            phase = "decoder";
+            root = await this.createRuntime();
+            const requestPath = join(root.path, "request.json");
+            const snapshotPath = join(root.path, "object.snapshot");
+            const replyPath = join(root.path, "reply.json");
+            await writeFile(snapshotPath, snapshot.bytes, {
+                flag: "wx",
+                mode: 0o600,
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            await writeFile(requestPath, JSON.stringify({ snapshot_path: snapshotPath, reply_path: replyPath }), { flag: "wx", mode: 0o600 });
+            const execution = await runOwnedCommand({
+                command: this.environment.REA_PWNTOOLS_PYTHON ?? "",
+                arguments: [
+                    "-I",
+                    fileURLToPath(this.profile.bridge),
+                    join(root.path, "resource.failure"),
+                    requestPath,
+                ],
+                cwd: root.path,
+                runId: `rea-artifact-decoder-${randomUUID()}`,
+                hostEnvironment: {
+                    ...this.environment,
+                    PWNLIB_NOTERM: "1",
+                    OPENBLAS_NUM_THREADS: "1",
+                    OMP_NUM_THREADS: "1",
+                },
+            }, {
+                timeoutMs: PWNTOOLS_LIMITS.timeoutMs,
+                diagnosticBytes: PWNTOOLS_LIMITS.diagnosticBytes,
+            }, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+            });
+            const capturedOutput = capturedPwntoolsOutput(execution);
+            let reply;
+            try {
+                const file = await readStableArtifact(replyPath, PWNTOOLS_LIMITS.outputBytes, options?.signal);
+                reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw new AnalysisCancelledError(OPERATION, { capturedOutput });
+                throw new AnalysisOutputError(OPERATION, `Owned pwntools decoder reply failed for ${input.path}: ${cause instanceof z.ZodError ? cause.issues[0]?.message + " at " + (cause.issues[0]?.path.map(String).join(".") ?? "root") : cause instanceof Error ? cause.message : String(cause)}`, { cause, capturedOutput });
+            }
+            if (!reply.ok) {
+                if (reply.reason === "unsupported-target")
+                    throw new AnalysisUnsupportedTargetError(OPERATION, input.path, reply.message, { capturedOutput });
+                if (reply.reason === "resource-limit")
+                    throw new AnalysisResourceConstraintError(OPERATION, "memory", reply.message, reply.reported_limits ?? null, { capturedOutput });
+                if (reply.reason === "format")
+                    throw new AnalysisInputError(OPERATION, { capturedOutput }, [
+                        {
+                            path: ["path"],
+                            reason: "invalid_format",
+                            message: reply.message,
+                        },
+                    ]);
+                if (reply.reason === "unavailable")
+                    throw pwntoolsUnavailable(reply.message, this.environment.REA_PWNTOOLS_PYTHON ?? "", undefined, capturedOutput, context);
+                if (reply.reason === "unsupported")
+                    throw new AnalysisCapabilityUnavailableError(this.identity.id, OPERATION, reply.message, { userMessage: reply.message, capturedOutput });
+                if (reply.reason === "output-limit")
+                    throw new AnalysisOutputError(OPERATION, reply.message, {
+                        capturedOutput,
+                    });
+                throw new ProviderAdapterError(this.identity.id, OPERATION, {
+                    diagnostics: {
+                        phase,
+                        failure_kind: reply.reason,
+                        reason: reply.message,
+                        stdout: execution.stdout.text,
+                        stderr: execution.stderr.text,
+                        captured_output: { ...capturedOutput },
+                    },
+                });
+            }
+            result = ok(await this.profile.project({
+                input,
+                payload: reply.value,
+                snapshot,
+                rootPath: root.path,
+                diagnostics: capturedOutput,
+                options,
+            }));
+        }
+        catch (cause) {
+            const evidence = await readPwntoolsFailureEvidence(cause, root?.path);
+            result = err(options?.signal?.aborted &&
+                (cause === options.signal.reason ||
+                    (cause instanceof Error && cause.name === "AbortError"))
+                ? new AnalysisCancelledError(OPERATION)
+                : pwntoolsDecoderFailure(cause, phase, selectedPath, executablePath, evidence, context));
+        }
+        if (root !== undefined) {
+            try {
+                await root.close();
+            }
+            catch (cause) {
+                return err(new ProviderCleanupError(this.identity.id, [root.path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    previous_error: result.ok
+                        ? null
+                        : projectAnalysisError(result.error),
+                    ...(result.ok
+                        ? {
+                            captured_output: {
+                                stdout: result.value.diagnostics.stdout,
+                                stderr: result.value.diagnostics.stderr,
+                                truncated: result.value.diagnostics.truncated,
+                            },
+                        }
+                        : {}),
+                }, { operation: OPERATION }));
+            }
+        }
+        return result.ok && options?.signal?.aborted
+            ? err(new AnalysisCancelledError(OPERATION, {
+                capturedOutput: {
+                    stdout: result.value.diagnostics.stdout,
+                    stderr: result.value.diagnostics.stderr,
+                    truncated: result.value.diagnostics.truncated,
+                },
+            }))
+            : result;
+    }
+}

package/dist/native/pwntools/PwntoolsFailures.js

@@ -0,0 +1,180 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { AnalysisError, } from "../../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, AnalysisResourceConstraintError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { ProviderSelectionError } from "../../domain/providerSelectionError.js";
+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
+import { PWNTOOLS_PROVIDER_IDENTITY, PWNTOOLS_LIMITS, PWNTOOLS_MEMORY_FAILURE_EXIT, PWNTOOLS_FILE_SIZE_FAILURE_EXIT, } from "./PwntoolsRelease.js";
+const DEFAULT_CONTEXT = {
+    operation: "inspect_binary_layout",
+    providerId: PWNTOOLS_PROVIDER_IDENTITY.id,
+};
+/** Keep read, engine, output and owned-lifecycle failure reasons distinct. */
+export const pwntoolsDecoderFailure = (cause, phase, path, executablePath = path, failureEvidence = {}, context = DEFAULT_CONTEXT) => {
+    const limitReport = failureEvidence.limits;
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof OwnedCommandFailure) {
+        const currentOutput = cause.snapshot === null
+            ? undefined
+            : capturedPwntoolsOutput(cause.snapshot);
+        const combinedOutput = context.precedingOutput === undefined
+            ? currentOutput
+            : currentOutput === undefined
+                ? context.precedingOutput
+                : {
+                    stdout: `[core decoder]\n${context.precedingOutput.stdout}\n[debugger]\n${currentOutput.stdout}`,
+                    stderr: `[core decoder]\n${context.precedingOutput.stderr}\n[debugger]\n${currentOutput.stderr}`,
+                    truncated: context.precedingOutput.truncated || currentOutput.truncated,
+                };
+        const outputOptions = combinedOutput === undefined
+            ? undefined
+            : { capturedOutput: combinedOutput };
+        if (cause.cleanupFailure !== null)
+            return new ProviderCleanupError(context.providerId, cause.resources, {
+                reason: cause.cleanupFailure,
+                ...(combinedOutput === undefined
+                    ? {}
+                    : {
+                        captured_output: { ...combinedOutput },
+                    }),
+                previous_error: {
+                    failure_kind: cause.reason,
+                    message: cause.message,
+                    exit_code: cause.snapshot?.exitCode ?? null,
+                    signal: cause.snapshot?.signal ?? null,
+                    stdout: cause.snapshot?.stdout.text ?? null,
+                    stderr: cause.snapshot?.stderr.text ?? null,
+                },
+            }, { operation: context.operation, cause });
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError(context.operation, outputOptions);
+        if (cause.reason === "timeout")
+            return new AnalysisTimeoutError(context.operation, PWNTOOLS_LIMITS.timeoutMs, outputOptions);
+        if (cause.reason === "output-limit")
+            return new AnalysisOutputError(context.operation, cause.message, outputOptions);
+        if (cause.reason === "process" &&
+            (cause.snapshot?.signal === "SIGXFSZ" ||
+                (failureEvidence.marker?.resource === "file-size" &&
+                    cause.snapshot?.exitCode === PWNTOOLS_FILE_SIZE_FAILURE_EXIT &&
+                    cause.snapshot.signal === null)))
+            return new AnalysisResourceConstraintError(context.operation, "file-size", (cause.snapshot.signal === "SIGXFSZ"
+                ? "Owned Python terminated with SIGXFSZ; the exact signal cause is unknown."
+                : "The owned Python bridge reported EFBIG while writing a file; the exact write failure cause is unknown.") +
+                (limitReport?.failure === null || limitReport === undefined
+                    ? ""
+                    : ` Effective limit report unavailable: ${limitReport.failure}`), limitReport?.limits ?? null, outputOptions);
+        if (cause.reason === "process" && cause.snapshot?.signal === "SIGXCPU")
+            return new AnalysisResourceConstraintError(context.operation, "cpu", "Owned Python terminated with SIGXCPU; the exact signal cause is unknown." +
+                (limitReport?.failure === null || limitReport === undefined
+                    ? ""
+                    : ` Effective limit report unavailable: ${limitReport.failure}`), limitReport?.limits ?? null, outputOptions);
+        if (cause.reason === "process" &&
+            failureEvidence.marker?.resource === "memory" &&
+            cause.snapshot?.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT &&
+            cause.snapshot.signal === null)
+            return new AnalysisResourceConstraintError(context.operation, "memory", "The owned Python bridge reported a memory allocation failure without a structured reply; the exact allocation cause is unknown." +
+                (limitReport?.failure === null || limitReport === undefined
+                    ? ""
+                    : ` Effective limit report unavailable: ${limitReport.failure}`), limitReport?.limits ?? null, outputOptions);
+    }
+    if (cause instanceof Error &&
+        "code" in cause &&
+        "syscall" in cause &&
+        typeof cause.syscall === "string" &&
+        cause.syscall.startsWith("spawn "))
+        return pwntoolsUnavailable(`Selected Python could not launch (${String(cause.code)}): ${executablePath}. Check the configured executable, its interpreter and host execute access.`, executablePath, String(cause.code), undefined, context);
+    if (cause instanceof ArtifactReaderFailure) {
+        if (cause.reason === "integrity")
+            return new AnalysisArtifactChangedError(context.operation, path, cause.message, {
+                cause,
+            });
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError(context.operation);
+        if (cause.reason === "limit" ||
+            cause.reason === "path" ||
+            cause.reason === "format")
+            return new AnalysisInputError(context.operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
+                    message: cause.message,
+                },
+            ]);
+    }
+    if (cause instanceof Error && "code" in cause) {
+        if (phase === "configuration")
+            return pwntoolsUnavailable(`Selected Python executable is unavailable (${String(cause.code)}): ${path}. Check the caller-selected path and execute access.`, path, String(cause.code), undefined, context);
+        if (phase === "artifact-read" &&
+            (cause.code === "EACCES" || cause.code === "EPERM"))
+            return new AnalysisAccessDeniedError(context.operation, path, cause.code, {
+                cause,
+            });
+        if (phase === "artifact-read" &&
+            (cause.code === "ENOENT" || cause.code === "ENOTDIR"))
+            return new AnalysisInputError(context.operation, { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_value",
+                    message: `Selected object could not be read (${String(cause.code)}): ${path}.`,
+                },
+            ]);
+    }
+    return new ProviderAdapterError(context.providerId, context.operation, {
+        cause,
+        diagnostics: {
+            phase,
+            path,
+            ...(context.precedingOutput === undefined
+                ? {}
+                : { preceding_output: { ...context.precedingOutput } }),
+            reason: cause instanceof Error ? cause.message : String(cause),
+            ...(failureEvidence.marker === undefined
+                ? {}
+                : { resource_failure_marker: { ...failureEvidence.marker } }),
+            ...(cause instanceof OwnedCommandFailure
+                ? {
+                    failure_kind: cause.reason,
+                    exit_code: cause.snapshot?.exitCode ?? null,
+                    signal: cause.snapshot?.signal ?? null,
+                    stdout: cause.snapshot?.stdout.text ?? null,
+                    stderr: cause.snapshot?.stderr.text ?? null,
+                    ...(cause.snapshot === null
+                        ? {}
+                        : {
+                            captured_output: {
+                                ...capturedPwntoolsOutput(cause.snapshot),
+                            },
+                        }),
+                }
+                : {}),
+        },
+    });
+};
+/** Report caller-selected engine absence with its actual configuration and host constraint. */
+export const pwntoolsUnavailable = (reason, path, systemCode, capturedOutput, context = DEFAULT_CONTEXT) => new ProviderSelectionError({
+    ...(capturedOutput === undefined ? {} : { capturedOutput }),
+    operation: context.operation,
+    reason: "provider_unavailable",
+    requestedProviderId: context.providerId,
+    candidateIds: [context.providerId],
+    rejections: [
+        {
+            providerId: context.providerId,
+            code: "provider_unavailable",
+            reason,
+            diagnostics: {
+                configuration_key: "REA_PWNTOOLS_PYTHON",
+                executable_path: path,
+                ...(systemCode === undefined ? {} : { system_code: systemCode }),
+            },
+        },
+    ],
+});
+/** Retain bounded text output and the shared supervisor's observed truncation flag. */
+export const capturedPwntoolsOutput = (snapshot) => ({
+    stdout: snapshot.stdout.text,
+    stderr: snapshot.stderr.text,
+    truncated: snapshot.diagnosticTruncated === true,
+});

package/dist/native/pwntools/PwntoolsLayoutProvider.js

@@ -0,0 +1,36 @@
+import { binaryLayoutPayloadSchema, binaryLayoutSchema, } from "../../domain/native/binaryLayout.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { PwntoolsDecoder } from "./PwntoolsDecoder.js";
+import { PWNTOOLS_PROVIDER_IDENTITY } from "./PwntoolsRelease.js";
+import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
+/** ELF-specific projection around the shared owned pwntools decoder boundary. */
+export class PwntoolsLayoutProvider extends PwntoolsDecoder {
+    constructor(environment, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-elf-layout-" })) {
+        super({
+            identity: PWNTOOLS_PROVIDER_IDENTITY,
+            operation: "inspect_binary_layout",
+            bridge: new URL("../../../bridge/pwntools/layout.py", import.meta.url),
+            payloadSchema: binaryLayoutPayloadSchema,
+            project: ({ input, payload, snapshot, diagnostics }) => {
+                const value = binaryLayoutSchema.safeParse({
+                    ...payload,
+                    artifact: {
+                        path: input.path,
+                        sha256: snapshot.sha256,
+                        bytes: snapshot.bytes.length,
+                    },
+                    diagnostics,
+                });
+                if (!value.success)
+                    throw new AnalysisOutputError("inspect_binary_layout", `ELF reply contains invalid source ranges or value meanings: ${value.error.issues[0]?.message ?? "schema mismatch"}`, { capturedOutput: diagnostics });
+                for (const table of value.data.packed_relative_relocations) {
+                    const start = Number(BigInt(table.location.offset));
+                    const length = Number(BigInt(table.location.bytes));
+                    if (!Buffer.from(table.encoded_bytes_base64, "base64").equals(snapshot.bytes.subarray(start, start + length)))
+                        throw new AnalysisOutputError("inspect_binary_layout", "Reported packed relocation bytes differ from the selected snapshot at their original file range.", { capturedOutput: diagnostics });
+                }
+                return value.data;
+            },
+        }, environment, launcher, createRuntime);
+    }
+}

package/dist/native/pwntools/PwntoolsRecordedCrashProvider.js

@@ -0,0 +1,75 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { recordedCrashPayloadSchema, recordedCrashSchema, } from "../../domain/native/recordedCrash.js";
+import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
+import { PwntoolsDecoder } from "./PwntoolsDecoder.js";
+import { PWNTOOLS_PROVIDER_IDENTITY } from "./PwntoolsRelease.js";
+import { validateRecordedCrashSources } from "./RecordedCrashSourceBindings.js";
+import { validateRecordedCrashStructure } from "./RecordedCrashStructureBindings.js";
+import { inspectPwndbgCore, recordedCrashStageOutput, } from "../pwndbg/PwndbgCoreContext.js";
+/** Preserve every recorded thread while optionally enriching the same owned snapshot. */
+export class PwntoolsRecordedCrashProvider extends PwntoolsDecoder {
+    constructor(environment, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-recorded-crash-" })) {
+        super({
+            identity: PWNTOOLS_PROVIDER_IDENTITY,
+            operation: "inspect_recorded_crash",
+            bridge: new URL("../../../bridge/pwntools/recorded_crash.py", import.meta.url),
+            payloadSchema: recordedCrashPayloadSchema,
+            project: async ({ input, payload, snapshot, rootPath, diagnostics, options, }) => {
+                const validate = (debuggerContext) => recordedCrashSchema.safeParse({
+                    ...payload,
+                    artifact: {
+                        path: input.path,
+                        sha256: snapshot.sha256,
+                        bytes: snapshot.bytes.length,
+                    },
+                    debugger: debuggerContext,
+                    decoder_diagnostics: diagnostics,
+                    diagnostics: debuggerContext.status === "available"
+                        ? recordedCrashStageOutput(diagnostics, debuggerContext.diagnostics)
+                        : diagnostics,
+                });
+                const checked = validate({ status: "not-requested" });
+                if (!checked.success)
+                    throw new AnalysisOutputError("inspect_recorded_crash", `Recorded core reply is invalid: ${checked.error.issues[0]?.message ?? "schema mismatch"}`, { capturedOutput: diagnostics });
+                const value = checked.data;
+                validateRecordedCrashStructure(value, snapshot.bytes, diagnostics);
+                const checkBytes = (raw, range) => {
+                    const start = Number(BigInt(range.offset));
+                    const length = Number(BigInt(range.bytes));
+                    if (!Buffer.from(raw, "base64").equals(snapshot.bytes.subarray(start, start + length)))
+                        throw new AnalysisOutputError("inspect_recorded_crash", "Reported raw note bytes differ from the selected snapshot.", { capturedOutput: diagnostics });
+                };
+                for (const note of value.notes) {
+                    checkBytes(note.owner_bytes_base64, note.owner_location);
+                    checkBytes(note.descriptor_bytes_base64, note.descriptor_location);
+                }
+                for (const padding of value.note_padding)
+                    checkBytes(padding.bytes_base64, padding.location);
+                validateRecordedCrashSources(value, snapshot.bytes, diagnostics);
+                for (const thread of value.threads)
+                    for (const register of thread.registers) {
+                        const start = Number(BigInt(register.location.offset));
+                        if (snapshot.bytes.readBigUInt64LE(start) !== BigInt(register.value))
+                            throw new AnalysisOutputError("inspect_recorded_crash", "Reported register value differs from its recorded source bytes.", { capturedOutput: diagnostics });
+                    }
+                if (!input.include_debugger_context)
+                    return value;
+                const context = await inspectPwndbgCore({
+                    environment,
+                    rootPath,
+                    diagnostics,
+                    options,
+                    ...(launcher === undefined ? {} : { launcher }),
+                });
+                const enriched = validate(context);
+                if (!enriched.success)
+                    throw new AnalysisOutputError("inspect_recorded_crash", `Recorded debugger context is invalid: ${enriched.error.issues[0]?.message ?? "schema mismatch"}`, {
+                        capturedOutput: context.status === "available"
+                            ? recordedCrashStageOutput(diagnostics, context.diagnostics)
+                            : diagnostics,
+                    });
+                return enriched.data;
+            },
+        }, environment, launcher, createRuntime);
+    }
+}

package/dist/native/pwntools/PwntoolsRelease.js

@@ -0,0 +1,19 @@
+/** Verified unchanged upstream profile for the Linux ELF adapter. */
+export const PWNTOOLS_PROVIDER_IDENTITY = {
+    id: "pwntools-elf",
+    name: "REA pwntools ELF adapter",
+    version: "pwntools@4.15.0;pyelftools@0.33;unicorn@2.1.2",
+};
+/** Bridge-reserved status for MemoryError when no structured reply can be written. */
+export const PWNTOOLS_MEMORY_FAILURE_EXIT = 75;
+/** Bridge-reserved status for an observed EFBIG failure without a complete reply. */
+export const PWNTOOLS_FILE_SIZE_FAILURE_EXIT = 76;
+/** Complete evidence budgets; address-space is separate from resident memory. */
+export const PWNTOOLS_LIMITS = {
+    inputBytes: 32 * 1024 * 1024,
+    outputBytes: 64 * 1024 * 1024,
+    diagnosticBytes: 1024 * 1024,
+    timeoutMs: 30_000,
+    addressSpaceBytes: 3 * 1024 * 1024 * 1024,
+    cpuSeconds: 30,
+};

package/dist/native/pwntools/PwntoolsResourceLimits.js

@@ -0,0 +1,76 @@
+import { join } from "node:path";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
+import { PWNTOOLS_MEMORY_FAILURE_EXIT, PWNTOOLS_FILE_SIZE_FAILURE_EXIT, } from "./PwntoolsRelease.js";
+import { z } from "zod";
+import { PWNTOOLS_LIMITS } from "./PwntoolsRelease.js";
+/** Actual limits reported by the owned bridge after lowering inherited soft limits. */
+export const pwntoolsResourceLimitsSchema = z.strictObject({
+    address_space_bytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(PWNTOOLS_LIMITS.addressSpaceBytes),
+    cpu_seconds: z.number().int().nonnegative().max(PWNTOOLS_LIMITS.cpuSeconds),
+    file_size_bytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(PWNTOOLS_LIMITS.outputBytes),
+});
+/** Read only bounded owned reports; unverified reserved statuses stay unclassified. */
+export const readPwntoolsFailureEvidence = async (cause, rootPath) => {
+    let limitReport;
+    let marker;
+    if (cause instanceof OwnedCommandFailure &&
+        cause.snapshot?.signal === null &&
+        (cause.snapshot.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT ||
+            cause.snapshot.exitCode === PWNTOOLS_FILE_SIZE_FAILURE_EXIT) &&
+        rootPath !== undefined) {
+        try {
+            const reported = await readStableArtifact(join(rootPath, "resource.failure"), 1);
+            const expected = cause.snapshot.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT ? "M" : "F";
+            if (!reported.bytes.equals(Buffer.from(expected, "ascii")))
+                throw new Error("Private bridge failure marker does not match the observed exit status.");
+            marker = {
+                resource: expected === "M" ? "memory" : "file-size",
+                failure: null,
+            };
+        }
+        catch (markerFailure) {
+            marker = {
+                resource: null,
+                failure: markerFailure instanceof Error
+                    ? markerFailure.message
+                    : String(markerFailure),
+            };
+        }
+    }
+    if (cause instanceof OwnedCommandFailure &&
+        (cause.snapshot?.signal === "SIGXCPU" ||
+            cause.snapshot?.signal === "SIGXFSZ" ||
+            ((cause.snapshot?.exitCode === PWNTOOLS_FILE_SIZE_FAILURE_EXIT ||
+                cause.snapshot?.exitCode === PWNTOOLS_MEMORY_FAILURE_EXIT) &&
+                cause.snapshot.signal === null)) &&
+        rootPath !== undefined) {
+        try {
+            const reported = await readStableArtifact(join(rootPath, "limits.json"), 4096);
+            limitReport = {
+                limits: pwntoolsResourceLimitsSchema.parse(JSON.parse(reported.bytes.toString("utf8"))),
+                failure: null,
+            };
+        }
+        catch (reportFailure) {
+            limitReport = {
+                limits: null,
+                failure: reportFailure instanceof Error
+                    ? reportFailure.message
+                    : String(reportFailure),
+            };
+        }
+    }
+    return {
+        ...(limitReport === undefined ? {} : { limits: limitReport }),
+        ...(marker === undefined ? {} : { marker }),
+    };
+};

package/dist/native/pwntools/RecordedCrashSourceBindings.js

@@ -0,0 +1,46 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { RECORDED_LINUX_AMD64_REGISTERS, } from "../../domain/native/recordedCrash.js";
+const registerOffsets = new Map(RECORDED_LINUX_AMD64_REGISTERS.map((name, index) => [name, 112 + index * 8]));
+/** Bind interpreted values and register identities to Linux amd64 source bytes. */
+export function validateRecordedCrashSources(report, snapshot, diagnostics) {
+    const fail = () => {
+        throw new AnalysisOutputError("inspect_recorded_crash", "Reported PID or signal value differs from its recorded Linux amd64 source bytes.", { capturedOutput: diagnostics });
+    };
+    const descriptor = (noteIndex, minimumBytes) => {
+        const note = report.notes[noteIndex];
+        if (note === undefined)
+            return fail();
+        const start = Number(BigInt(note.descriptor_location.offset));
+        const length = Number(BigInt(note.descriptor_location.bytes));
+        if (length < minimumBytes)
+            return fail();
+        return snapshot.subarray(start, start + length);
+    };
+    // Fixed offsets independently checked against unchanged pwntools 4.15.0
+    // elf_prstatus_amd64 / elf_siginfo_64; this is the sole supported note ABI.
+    for (const thread of report.threads) {
+        const bytes = descriptor(thread.note_index, 336);
+        if (thread.historical_pid !== bytes.readInt32LE(32) ||
+            thread.recorded_current_signal !== bytes.readInt16LE(12))
+            fail();
+        const note = report.notes[thread.note_index];
+        if (note === undefined)
+            return fail();
+        for (const register of thread.registers) {
+            const offset = registerOffsets.get(register.name);
+            if (offset === undefined ||
+                BigInt(register.location.offset) !==
+                    BigInt(note.descriptor_location.offset) + BigInt(offset))
+                throw new AnalysisOutputError("inspect_recorded_crash", "Reported register source does not match its Linux amd64 register identity.", { capturedOutput: diagnostics });
+        }
+    }
+    for (const signal of report.signals) {
+        const bytes = descriptor(signal.note_index, 32);
+        if (signal.number !== bytes.readInt32LE(0) ||
+            signal.errno !== bytes.readInt32LE(4) ||
+            signal.code !== bytes.readInt32LE(8) ||
+            (signal.fault_address !== null &&
+                BigInt(signal.fault_address) !== bytes.readBigUInt64LE(16)))
+            fail();
+    }
+}