rea-agents 3.1.0 → 3.2.0

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -1,6 +1,5 @@
 import { WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON } from "../process/WindowsAuthority.js";
 import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
-import { GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS, GHIDRA_MAX_LINE_BYTES, GHIDRA_REQUEST_TIMEOUT_MS, } from "./GhidraDefaults.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
 /** Public identity committed by every Ghidra-backed observation. */
@@ -17,27 +16,9 @@ export const GHIDRA_PROVIDER_TOOL_CONTRACTS = Object.freeze([...GHIDRA_INVENTORY
         throw new TypeError(`Missing provider-neutral contract for ${operation}`);
     return contract;
 }));
-const PAGINATED_OPERATIONS = new Set([
-    "list_names",
-    "list_procedures",
-    "list_strings",
-    "search_procedures",
-    "search_strings",
-    "procedure_references",
-    "read_function_instructions",
-    "analyze_function",
-]);
-const SEARCH_OPERATIONS = new Set([
-    "search_procedures",
-    "search_strings",
-]);
-const DECOMPILE_OPERATIONS = new Set([
-    "procedure_pseudo_code",
-    "analyze_function",
-]);
 /** Health limitations shared by every Ghidra-backed capability. */
 export const healthLimitations = Object.freeze([
-    "The session serves operations only after default Ghidra auto-analysis completes; an analysis timeout fails the open instead of exposing partial results.",
+    "The session serves operations only after Ghidra reports default auto-analysis complete; incomplete analysis does not expose partial results.",
     "The imported Program and temporary project are ephemeral, read-only to REA, and deleted on close.",
 ]);
 /** Additional limitations applied to the experimental Windows x64 P0 boundary. */
@@ -73,7 +54,6 @@ export const limitationsFor = (operation) => {
             return [
                 ...common,
                 "Only Ghidra-defined string Data is observed; charset is reported, while a non-missing terminator cannot distinguish a present terminator from a fixed or Pascal layout.",
-                "Returned values are bounded to 1,024 Unicode code points and mark value_truncated instead of silently crossing the wire budget.",
             ];
         case "list_segments":
             return [
@@ -82,26 +62,23 @@ export const limitationsFor = (operation) => {
             ];
         case "search_procedures":
         case "search_strings":
-            return [
-                ...common,
-                "Literal search enforces 1,000,000 cumulative work units; regex mode also accepts only a conservative finite Java-regex subset with 10,000 static paths and 4,096 UTF-16 code units per candidate.",
-            ];
+            return common;
         case "procedure_pseudo_code":
             return [
                 ...common,
-                "Pseudocode is Ghidra decompiler output, not original source and not text-equivalent to Hopper output; each decompile has a 30-second native deadline.",
+                "Pseudocode is Ghidra decompiler output, not original source and not text-equivalent to Hopper output.",
                 "External functions and functions without an analyzable body return null; other decompiler failures remain explicit.",
             ];
         case "read_function_instructions":
             return [
                 ...common,
-                "This bounded fast path reads only the requested function instruction window and does not invoke the decompiler or whole-program string/name inventories.",
+                "This fast path reads only the requested function and does not invoke the decompiler or whole-program string/name inventories.",
                 "Instruction text is Ghidra-specific and does not claim textual equivalence with Hopper output.",
             ];
         case "procedure_assembly":
             return [
                 ...common,
-                "Assembly is Ghidra Listing text and fails rather than silently truncating when the 100,000-instruction or 1 MiB wire bound is exceeded.",
+                "Assembly is Ghidra Listing text and does not claim textual equivalence with Hopper output.",
             ];
         case "procedure_callers":
         case "procedure_callees":
@@ -120,7 +97,6 @@ export const limitationsFor = (operation) => {
                 ...common,
                 "Reference kinds are direct Ghidra ReferenceManager observations; unresolved computed flows without a target are absent and remain unknown.",
                 "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
-                "Instruction scans stop at max_instructions; a truncated scan reports an unknown total and no false continuation.",
             ];
         case "analyze_function":
             return [
@@ -128,7 +104,7 @@ export const limitationsFor = (operation) => {
                 "The dossier combines Ghidra FunctionManager, Listing, ReferenceManager, BasicBlockModel, and decompiler observations; provider-specific pseudocode and assembly are not cross-provider text invariants.",
                 "Resolved reference metadata identifies computed, indirect, external, call, jump, and data edges; unresolved targetless flows remain unknown, and function classifications distinguish thunks and externals.",
                 "Synthetic Ghidra entry-point references without actionable memory sources are omitted.",
-                "The Java bridge serializes one function request per Program through a bounded 32-request queue and applies a 30-second native decompilation deadline.",
+                "The Java bridge serializes one function request per Program and lets each decompilation run until it completes or the caller cancels.",
             ];
         default:
             return common;
@@ -142,14 +118,8 @@ export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((co
     return Object.freeze({
         provider: GHIDRA_PROVIDER_IDENTITY,
         operation,
-        inputContractVersion: 1,
-        outputContractVersion: 1,
         available: true,
         reason: null,
-        pagination: PAGINATED_OPERATIONS.has(contract.name)
-            ? "offset"
-            : "none",
-        exhaustive: !PAGINATED_OPERATIONS.has(contract.name),
         effects: Object.freeze({
             mutatesArtifact: false,
             launchesProcess: true,
@@ -159,17 +129,6 @@ export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((co
             changesPermissions: false,
             requiresRoot: false,
         }),
-        limits: Object.freeze({
-            maxResults: PAGINATED_OPERATIONS.has(contract.name)
-                ? SEARCH_OPERATIONS.has(contract.name)
-                    ? 100
-                    : 500
-                : null,
-            maxPayloadBytes: GHIDRA_MAX_LINE_BYTES,
-            timeoutMs: DECOMPILE_OPERATIONS.has(contract.name)
-                ? GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS
-                : GHIDRA_REQUEST_TIMEOUT_MS,
-        }),
         limitations: Object.freeze(limitationsFor(contract.name)),
     });
 }));

package/dist/ghidra/GhidraRequestQueue.js

@@ -1,41 +1,28 @@
-import { performance } from "node:perf_hooks";
 import { err } from "../domain/result.js";
-/** Bounded FIFO that admits one Ghidra Program request at a time. */
+/** FIFO that admits one Ghidra Program request at a time. */
 export class GhidraRequestQueue {
-    maximum;
     execute;
     failure;
     #queue = [];
     #active = false;
-    #size = 0;
-    constructor(maximum, execute, failure) {
-        this.maximum = maximum;
+    constructor(execute, failure) {
         this.execute = execute;
         this.failure = failure;
     }
-    /** Queue one request, counting queue wait against its declared deadline. */
+    /** Queue one request until it completes, is cancelled, or the session closes. */
     run(method, parameters, options) {
         if (options.signal?.aborted === true)
             return Promise.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
-        if (options.timeoutMs <= 0)
-            return Promise.resolve(err(this.failure("timeout", "Ghidra request deadline elapsed", options.timeoutMs)));
-        if (this.#size >= this.maximum)
-            return Promise.resolve(err(this.failure("protocol", `Ghidra serial request queue reached its ${String(this.maximum)}-request limit`)));
-        this.#size += 1;
         return new Promise((resolve) => {
             let entry;
             const onAbort = options.signal === undefined
                 ? undefined
                 : () => this.#rejectQueued(entry, err(this.failure("cancelled", "Ghidra request was cancelled")));
-            const timer = setTimeout(() => this.#rejectQueued(entry, err(this.failure("timeout", "Ghidra request deadline elapsed in the serial queue", options.timeoutMs))), options.timeoutMs);
             entry = {
                 method,
                 parameters,
                 signal: options.signal,
-                timeoutMs: options.timeoutMs,
-                deadline: performance.now() + options.timeoutMs,
                 resolve,
-                timer,
                 onAbort,
             };
             this.#queue.push(entry);
@@ -48,7 +35,6 @@ export class GhidraRequestQueue {
     failQueued(failure) {
         for (const entry of this.#queue.splice(0)) {
             this.#release(entry);
-            this.#size -= 1;
             entry.resolve(err(failure));
         }
     }
@@ -59,25 +45,17 @@ export class GhidraRequestQueue {
         if (entry === undefined)
             return;
         this.#release(entry);
-        const remaining = entry.deadline - performance.now();
-        if (entry.signal?.aborted === true || remaining <= 0) {
-            this.#size -= 1;
-            entry.resolve(err(entry.signal?.aborted === true
-                ? this.failure("cancelled", "Ghidra request was cancelled")
-                : this.failure("timeout", "Ghidra request deadline elapsed in the serial queue", entry.timeoutMs)));
+        if (entry.signal?.aborted === true) {
+            entry.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
             this.#drain();
             return;
         }
         this.#active = true;
-        void this.execute(entry.method, entry.parameters, {
-            ...(entry.signal === undefined ? {} : { signal: entry.signal }),
-            timeoutMs: remaining,
-        })
+        void this.execute(entry.method, entry.parameters, entry.signal === undefined ? {} : { signal: entry.signal })
             .then(entry.resolve)
             .catch(() => entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly"))))
             .finally(() => {
             this.#active = false;
-            this.#size -= 1;
             this.#drain();
         });
     }
@@ -87,11 +65,9 @@ export class GhidraRequestQueue {
             return;
         this.#queue.splice(index, 1);
         this.#release(entry);
-        this.#size -= 1;
         entry.resolve(result);
     }
     #release(entry) {
-        clearTimeout(entry.timer);
         if (entry.signal !== undefined && entry.onAbort !== undefined)
             entry.signal.removeEventListener("abort", entry.onAbort);
     }

package/dist/ghidra/GhidraResponseBuffer.js

@@ -1,4 +1,4 @@
-/** Splits fragmented UTF-8 socket data while enforcing a byte limit per line. */
+/** Splits fragmented UTF-8 socket data into response lines. */
 export class GhidraResponseBuffer {
     #options;
     #buffer = "";
@@ -12,17 +12,11 @@ export class GhidraResponseBuffer {
         while (newline >= 0) {
             const encodedLine = this.#buffer.slice(0, newline);
             this.#buffer = this.#buffer.slice(newline + 1);
-            if (Buffer.byteLength(encodedLine) > this.#options.maxLineBytes) {
-                this.#options.onFailure("Ghidra response exceeded the maximum line size");
-                return;
-            }
             const line = encodedLine.trim();
             if (line.length > 0)
                 this.#options.onLine(line);
             newline = this.#buffer.indexOf("\n");
         }
-        if (Buffer.byteLength(this.#buffer) > this.#options.maxLineBytes)
-            this.#options.onFailure("Ghidra response exceeded the maximum line size");
     }
     /** Drop any incomplete line when a session closes. */
     reset() {

package/dist/ghidra/GhidraSessionValues.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { err, ok } from "../domain/result.js";
-import { GHIDRA_BRIDGE_VERSION } from "./GhidraDefaults.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 /** Exact methods proved by the bridge handshake after auto-analysis. */
@@ -14,7 +13,6 @@ const capabilitySchema = z.enum(GHIDRA_SESSION_CAPABILITIES);
 const sessionInfoSchema = z
     .object({
     name: z.literal("REA Ghidra bridge"),
-    bridge_version: z.literal(GHIDRA_BRIDGE_VERSION),
     run_id: z.string().uuid(),
     profile_digest: z.string().regex(/^[a-f0-9]{64}$/u),
     provider: z

package/dist/ghidra/GhidraTransport.js

@@ -1,7 +1,6 @@
 import { access, open } from "node:fs/promises";
 import { err, ok } from "../domain/result.js";
 import { GhidraSessionError } from "./GhidraSessionError.js";
-const MAX_ENDPOINT_BYTES = 1024;
 /** Observe a ready endpoint, returning null while its bridge is not listening. */
 export const observeGhidraEndpoint = async (endpoint) => {
     if (endpoint.transport === "unix-socket") {
@@ -25,11 +24,10 @@ export const observeGhidraEndpoint = async (endpoint) => {
             : err(endpointFailure(endpoint, "Ghidra endpoint observation failed", cause));
     }
     try {
-        const bytes = Buffer.alloc(MAX_ENDPOINT_BYTES + 1);
-        const observed = await handle.read(bytes, 0, bytes.length, 0);
-        if (observed.bytesRead === 0 || observed.bytesRead > MAX_ENDPOINT_BYTES)
+        const encoded = await handle.readFile("utf8");
+        if (encoded.length === 0)
             return err(endpointFailure(endpoint, "Ghidra TCP endpoint is invalid"));
-        return parseTcpEndpoint(endpoint, bytes.subarray(0, observed.bytesRead).toString("utf8"));
+        return parseTcpEndpoint(endpoint, encoded);
     }
     catch (cause) {
         return err(endpointFailure(endpoint, "Ghidra endpoint read failed", cause));
@@ -44,8 +42,7 @@ const parseTcpEndpoint = (endpoint, encoded) => {
         if (typeof value !== "object" ||
             value === null ||
             Array.isArray(value) ||
-            !hasExactKeys(value, ["host", "port", "schema_version"]) ||
-            value.schema_version !== 1 ||
+            !hasExactKeys(value, ["host", "port"]) ||
             value.host !== "127.0.0.1" ||
             !Number.isSafeInteger(value.port) ||
             typeof value.port !== "number" ||

package/dist/ghidra/protocol.js

@@ -12,8 +12,8 @@ const responseSchema = z.discriminatedUnion("ok", [
         ok: z.literal(false),
         error: z
             .object({
-            code: z.string().min(1).max(128),
-            message: z.string().min(1).max(4_096),
+            code: z.string().min(1),
+            message: z.string().min(1),
         })
             .strict(),
     }),

package/dist/hopper/BridgeLauncher.js

@@ -5,10 +5,12 @@ import { promisify } from "node:util";
 import { HopperCancelledError, HopperProcessError, HopperStartError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { execFileOutput } from "../process/ExecFileOutput.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
 import { selectLinuxPrivateDisplayStrategy, } from "./LinuxPrivateDisplayProbe.js";
 import writeFileAtomic from "write-file-atomic";
+import { acquireHopperTargetLease } from "./HopperTargetLease.js";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
 /**
@@ -33,57 +35,68 @@ export class HopperApplicationLauncher {
         this.dependencies = dependencies;
     }
     async launch(session, options = {}) {
-        const bootstrapPath = `${session.directory}/bootstrap.py`;
-        const ownsProcessLifetime = usesLinuxDemo(this.options);
-        const source = [
-            `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
-            `REA_TOKEN = ${JSON.stringify(session.token)}`,
-            `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
-            `REA_TARGET_PATH = ${JSON.stringify(this.options.targetPath)}`,
-            `REA_OWNS_PROCESS_LIFETIME = ${ownsProcessLifetime ? "True" : "False"}`,
-            `exec(compile(open(${JSON.stringify(this.options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(this.options.bridgeScriptPath)}, 'exec'))`,
-            "",
-        ].join("\n");
+        const leaseResult = await this.#acquireTargetLease(session.runId);
+        if (!leaseResult.ok)
+            return leaseResult;
+        const lease = leaseResult.value;
+        let leaseTransferred = false;
         try {
-            await writeFile(bootstrapPath, source, { encoding: "utf8", mode: 0o600 });
-            await chmod(bootstrapPath, 0o600);
+            const ownsProcessLifetime = usesLinuxDemo(this.options);
+            const bootstrap = await this.#writeBootstrap(session, ownsProcessLifetime);
+            if (!bootstrap.ok)
+                return bootstrap;
+            const launched = await this.#launchPreparedTarget({
+                session,
+                signal: options.signal,
+                bootstrapPath: bootstrap.value,
+                ownsProcessLifetime,
+                lease,
+            });
+            leaseTransferred = launched.ok;
+            return launched;
         }
-        catch (cause) {
-            return err(new HopperStartError({ cause }));
+        finally {
+            if (!leaseTransferred)
+                await lease?.release();
         }
+    }
+    async #launchPreparedTarget(input) {
+        const { session, signal, bootstrapPath, ownsProcessLifetime, lease } = input;
         const action = this.options.targetKind === "database" ? "--database" : "--executable";
-        const args = [
+        const argumentsForTarget = [
             ...this.options.loaderArgs,
             "--analysis",
-            "--python",
+            "-Y",
             bootstrapPath,
             action,
             this.options.targetPath,
         ];
         try {
-            if (options.signal?.aborted === true)
+            if (signal?.aborted === true)
                 return err(new HopperCancelledError());
-            const display = await this.#privateDisplay(options.signal);
+            const display = await this.#privateDisplay(signal);
             if (!display.ok)
                 return err(display.error);
-            const prepared = await prepareHopperApplication(this.options.launcherPath, options.signal);
+            const prepared = await prepareHopperApplication(this.options.launcherPath, signal);
             if (!prepared)
                 return err(new HopperCancelledError());
-            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,
-                arguments: linuxDemo?.args ?? args,
-                runId: session.runId,
-                expectedCommand: ownershipCommand,
+            const linuxDemo = linuxDemoLaunch(this.options, session, argumentsForTarget, display.strategy);
+            const started = await launchHopperProcess({
+                options: this.options,
+                session,
+                bootstrapPath,
+                ownsProcessLifetime,
+                argumentsForTarget,
+                linuxDemo,
+                signal,
             });
-            const child = started.process;
-            const pid = started.ownership.leaderPid;
+            if (started === null)
+                return err(new HopperCancelledError());
+            const cleanup = () => cleanupOwnedProcessGroup(started.ownership).finally(() => lease?.release());
             const ownership = {
-                schema_version: 1,
                 run_id: session.runId,
-                pid,
-                process_group_id: pid,
+                pid: started.ownership.leaderPid,
+                process_group_id: started.ownership.leaderPid,
                 parent_pid: process.pid,
                 launcher: linuxDemo?.command ?? this.options.launcherPath,
                 created_at: new Date().toISOString(),
@@ -96,17 +109,50 @@ export class HopperApplicationLauncher {
                 return err(new HopperStartError({ cause }));
             }
             return ok({
-                process: child,
+                process: started.process,
                 ownsProcessLifetime: true,
                 ownership: started.ownership,
                 shutdownMode: ownsProcessLifetime
                     ? "process-cleanup"
                     : "bridge-request",
-                cleanup: () => cleanupOwnedProcessGroup(started.ownership),
+                cleanup,
+            });
+        }
+        catch (cause) {
+            return err(hopperLaunchFailure(cause, signal));
+        }
+    }
+    async #acquireTargetLease(runId) {
+        if ((this.dependencies.platform ?? process.platform) !== "darwin")
+            return ok(undefined);
+        try {
+            const acquisition = await (this.dependencies.acquireTargetLease ?? acquireHopperTargetLease)({
+                targetPath: this.options.targetPath,
+                targetKind: this.options.targetKind,
+                loaderArgs: this.options.loaderArgs,
+                runId,
             });
+            if (!acquisition.acquired)
+                return err(new HopperStartError({
+                    ownerRunId: acquisition.owner.runId,
+                    userMessage: `This Hopper target is already open in REA session ${acquisition.owner.runId}. ` +
+                        "Use that REA session or close it before opening this target again.",
+                }));
+            return ok(acquisition.lease);
+        }
+        catch (cause) {
+            return err(new HopperStartError({ cause }));
+        }
+    }
+    async #writeBootstrap(session, ownsProcessLifetime) {
+        const bootstrapPath = `${session.directory}/bootstrap.py`;
+        try {
+            await writeFile(bootstrapPath, bridgeBootstrapSource(session, this.options, ownsProcessLifetime), { encoding: "utf8", mode: 0o600 });
+            await chmod(bootstrapPath, 0o600);
+            return ok(bootstrapPath);
         }
         catch (cause) {
-            return err(hopperLaunchFailure(cause, options.signal));
+            return err(new HopperStartError({ cause }));
         }
     }
     async #privateDisplay(signal) {
@@ -127,6 +173,32 @@ export class HopperApplicationLauncher {
             };
     }
 }
+const bridgeBootstrapSource = (session, options, ownsProcessLifetime) => [
+    `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
+    `REA_TOKEN = ${JSON.stringify(session.token)}`,
+    `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
+    `REA_TARGET_PATH = ${JSON.stringify(options.targetPath)}`,
+    `REA_OWNS_PROCESS_LIFETIME = ${ownsProcessLifetime ? "True" : "False"}`,
+    `exec(compile(open(${JSON.stringify(options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(options.bridgeScriptPath)}, 'exec'))`,
+    "",
+].join("\n");
+const launchHopperProcess = async (input) => {
+    const ownershipCommand = input.linuxDemo?.ownershipCommand ?? input.options.launcherPath;
+    const spawn = (arguments_) => spawnOwnedProviderProcess({
+        command: input.options.launcherPath,
+        arguments: arguments_,
+        runId: input.session.runId,
+        expectedCommand: ownershipCommand,
+    });
+    if (input.linuxDemo !== undefined)
+        return spawnOwnedProviderProcess({
+            command: input.linuxDemo.command,
+            arguments: input.linuxDemo.args,
+            runId: input.session.runId,
+            expectedCommand: ownershipCommand,
+        });
+    return spawn(input.argumentsForTarget);
+};
 export const linuxDemoLaunch = (options, session, hopperArgs, strategy) => {
     if (!usesLinuxDemo(options) || options.demoHelperPath === undefined)
         return undefined;
@@ -194,7 +266,11 @@ const hopperApplicationBundle = (launcherPath) => {
 };
 const processIsRunning = async (executablePath) => {
     try {
-        const processes = await execFileAsync("/bin/ps", ["-ax", "-o", "command="]);
+        const processes = await execFileOutput("/bin/ps", [
+            "-ax",
+            "-o",
+            "command=",
+        ]);
         return processes.stdout
             .split("\n")
             .some((command) => command.trim() === executablePath);

package/dist/hopper/HopperAnalysisProfile.js

@@ -25,7 +25,7 @@ export const resolveHopperAnalysisProfile = async (target, options) => {
         version: `launcher-sha256:${launcherDigest.value}`,
     };
     return ok({
-        profile: createAnalysisProfile(provider, 1, {
+        profile: createAnalysisProfile(provider, {
             target_kind: target.kind,
             target_format: target.format,
             architecture: target.architecture ?? null,

package/dist/hopper/HopperCleanup.js

@@ -11,7 +11,9 @@ export const cleanupHopperSession = async (input) => {
         cleanupResult: undefined,
         shutdownConfirmed: false,
     };
-    await report(input.progress, 0, "requesting Hopper document shutdown");
+    await report(input.progress, 0, input.retainDocument
+        ? "detaching REA from the Hopper document"
+        : "requesting Hopper document shutdown");
     await requestShutdown(input, state);
     await report(input.progress, 0.35, "releasing Hopper bridge transport");
     input.releaseTransport(input.socket);
@@ -33,7 +35,9 @@ const requestShutdown = async (input, state) => {
         return;
     }
     const shutdown = await input
-        .request("shutdown")
+        .request(input.retainDocument || input.launch?.shutdownMode === "process-cleanup"
+        ? "shutdown"
+        : "shutdown_document")
         .catch(() => err(new HopperProcessError(null)));
     if (shutdown.ok &&
         isHopperCleanupRequired(shutdown.value) &&
@@ -141,7 +145,6 @@ const activityDetails = (activity) => ({
     request_id: activity.requestId,
     operation: activity.operation,
     elapsed_ms: activity.elapsedMs,
-    timeout_ms: activity.timeoutMs,
     caller_state: activity.callerState,
     queued_requests: activity.queuedRequests,
 });

package/dist/hopper/HopperClient.js

@@ -17,7 +17,6 @@ import { HopperRequestQueue, } from "./HopperRequestQueue.js";
 import { HopperResponseStream } from "./HopperResponseStream.js";
 import { responseResult, } from "./protocol.js";
 const SHUTDOWN_TIMEOUT_MS = 30_000;
-const MAX_QUEUED_REQUESTS = 64;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
 /** Safe launcher telemetry; stderr content is intentionally never exposed. */
 /**
@@ -60,10 +59,9 @@ export class HopperClient {
         this.#logger = options.logger ?? silentLogger;
         this.#options = {
             ...options,
-            requestTimeoutMs: options.requestTimeoutMs ?? 30_000,
             startupTimeoutMs: options.startupTimeoutMs ?? 120_000,
         };
-        this.#requests = new HopperRequestQueue(MAX_QUEUED_REQUESTS, ({ id, method, params }, failed) => {
+        this.#requests = new HopperRequestQueue(({ id, method, params }, failed) => {
             const socket = this.#socket;
             const token = this.#token;
             if (socket === undefined || socket.destroyed || token === undefined) {
@@ -255,6 +253,7 @@ export class HopperClient {
                 logger: this.#logger,
                 onDiagnostic: this.#options.onDiagnostic,
                 request: (method) => this.#request(method, {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }),
+                retainDocument: options.retainDocument === true,
                 releaseTransport: (socket) => {
                     this.#failAll(new HopperProcessError(null));
                     if (socket !== undefined)
@@ -304,18 +303,16 @@ export class HopperClient {
         return err(new HopperTimeoutError(this.#options.startupTimeoutMs));
     }
     async #request(method, params, options) {
+        const id = this.#nextId++;
         const socket = this.#socket;
         const token = this.#token;
         if (socket === undefined || socket.destroyed || token === undefined) {
-            return err(new HopperProcessError(null));
+            return err(new HopperProcessError(null, undefined, method, id));
         }
         if (options.signal?.aborted === true)
             return err(new HopperCancelledError());
-        const id = this.#nextId++;
         const startedAt = performance.now();
-        const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
         const result = await this.#requests.run(id, method, params, {
-            timeoutMs,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
             ...(options.progress !== undefined ? { progress: options.progress } : {}),
         });

package/dist/hopper/HopperProcessDiagnostic.js

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

package/dist/hopper/HopperProvider.js

@@ -34,15 +34,8 @@ const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract)
     return Object.freeze({
         provider: IDENTITY,
         operation,
-        inputContractVersion: 1,
-        outputContractVersion: 1,
         available: true,
         reason: null,
-        pagination: isRecord(contract.inputSchema.properties) &&
-            "offset" in contract.inputSchema.properties
-            ? "offset"
-            : "none",
-        exhaustive: false,
         effects: Object.freeze({
             mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
             launchesProcess: true,
@@ -52,19 +45,11 @@ const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract)
             changesPermissions: false,
             requiresRoot: false,
         }),
-        limits: Object.freeze({
-            maxResults: null,
-            maxPayloadBytes: contract.name === "read_bytes" ? 4_096 : null,
-            timeoutMs: null,
-        }),
         limitations: Object.freeze([
             "Results depend on Hopper's completed static analysis.",
         ]),
     });
 }));
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /** Concrete analysis provider backed by REA's private Hopper bridge. */
 export class HopperProvider {
     config;
@@ -209,7 +194,6 @@ export class HopperProvider {
                                 requestId: activity.requestId,
                                 operation: activity.operation,
                                 elapsedMs: activity.elapsedMs,
-                                timeoutMs: activity.timeoutMs,
                                 callerState: activity.callerState,
                             },
                         queuedRequests: activity?.queuedRequests ?? 0,