rea-agents 2.4.0 → 3.0.0

package/dist/hopper/HopperClient.js

@@ -2,21 +2,22 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { access } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperStartError, hopperStartupFailure, HopperTimeoutError, } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError, HopperCancelledError, HopperProcessError, HopperProtocolError, HopperRemoteError, HopperStartError, hopperStartupFailure, HopperTimeoutError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 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 { cleanupHopperSession } from "./HopperCleanup.js";
+import { 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;
+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. */
 /**
@@ -29,7 +30,8 @@ const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
  */
 export class HopperClient {
     #options;
-    #pending = new PendingOperations();
+    #requests;
+    #responses;
     #logger;
     #socket;
     #launch;
@@ -38,7 +40,6 @@ export class HopperClient {
     #token;
     #lineage = new ProviderRunLineage();
     #nextId = 1;
-    #buffer = "";
     #closing = false;
     #launcherExitCode;
     #launcherFailureDiagnostic;
@@ -46,7 +47,7 @@ export class HopperClient {
     #startPromise;
     #closePromise;
     #onSocketData = (chunk) => {
-        this.#onData(chunk);
+        this.#responses.push(chunk);
     };
     #onSocketError = () => {
         this.#failAll(new HopperProcessError(null));
@@ -62,11 +63,33 @@ export class HopperClient {
             requestTimeoutMs: options.requestTimeoutMs ?? 30_000,
             startupTimeoutMs: options.startupTimeoutMs ?? 120_000,
         };
+        this.#requests = new HopperRequestQueue(MAX_QUEUED_REQUESTS, ({ id, method, params }, failed) => {
+            const socket = this.#socket;
+            const token = this.#token;
+            if (socket === undefined || socket.destroyed || token === undefined) {
+                failed();
+                return;
+            }
+            socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
+                if (cause !== undefined && cause !== null)
+                    failed();
+            });
+        });
+        this.#responses = new HopperResponseStream({
+            accept: (message) => this.#acceptBridgeMessage(message),
+            hasQueued: (id) => this.#requests.hasQueued(id),
+            nextRequestId: () => this.#nextId,
+            abort: (message, cause) => this.#abortProtocol(message, cause),
+        });
     }
     /** Latest token-verified launcher lineage for the active run. */
     runtimeLineage() {
         return this.#lineage.snapshot();
     }
+    /** Observe a request that still occupies Hopper after caller timeout/cancel. */
+    requestActivity() {
+        return this.#requests.activity();
+    }
     /** Launch the bridge once and complete its authenticated health handshake. */
     start(signal) {
         if (this.#closePromise !== undefined) {
@@ -186,20 +209,29 @@ export class HopperClient {
         const started = await this.start(options.signal);
         if (!started.ok)
             return started;
-        return this.#request(name, arguments_, options);
+        const result = await this.#request(name, arguments_, options);
+        return !result.ok &&
+            result.error instanceof HopperRemoteError &&
+            result.error.diagnosticType === "capability_unavailable"
+            ? err(new AnalysisCapabilityUnavailableError("hopper", name, result.error.safeMessage))
+            : result;
     }
     /** Stop the bridge, settle outstanding requests, and remove session artifacts. */
     close() {
+        return this.closeWithOutcome().then(() => undefined);
+    }
+    /** Stop the bridge and report whether every owned resource was verified clean. */
+    closeWithOutcome(options = {}) {
         const starting = this.#startPromise;
         const controller = this.#startupController;
         controller?.abort();
-        this.#closePromise ??= Promise.resolve().then(() => this.#close(starting, controller));
+        this.#closePromise ??= Promise.resolve().then(() => this.#close(starting, controller, options));
         return this.#closePromise;
     }
-    async #close(starting, controller) {
+    async #close(starting, controller, options) {
         try {
             await starting?.catch(() => undefined);
-            await this.#cleanup();
+            return await this.#cleanup(options);
         }
         finally {
             if (this.#startPromise === starting)
@@ -210,63 +242,39 @@ export class HopperClient {
             this.#closePromise = undefined;
         }
     }
-    async #cleanup() {
+    async #cleanup(options = {}) {
         this.#closing = true;
         try {
-            const socket = this.#socket;
-            let cleanupResult;
-            if (socket !== undefined && !socket.destroyed) {
-                const shutdown = await this.#request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
-                if (shutdown.ok &&
-                    isHopperCleanupRequired(shutdown.value) &&
-                    this.#launch?.shutdownByCleanup === true &&
-                    this.#launch.cleanup !== undefined) {
-                    cleanupResult = await this.#launch
-                        .cleanup()
-                        .catch(providerCleanupFailure);
-                    if (!cleanupResult.cleaned) {
-                        await this.#fallbackDocumentShutdown();
-                        cleanupResult = await this.#launch
-                            .cleanup()
-                            .catch(providerCleanupFailure);
-                    }
-                }
-                else if (!shutdown.ok ||
-                    !isHopperShutdownAcknowledgement(shutdown.value))
-                    this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
-            }
-            this.#failAll(new HopperProcessError(null));
-            if (socket !== undefined)
-                this.#detachSocket(socket);
-            socket?.destroy();
+            return await cleanupHopperSession({
+                socket: this.#socket,
+                launch: this.#launch,
+                processSupervisor: this.#process,
+                runtimeRoot: this.#runtimeRoot,
+                activeRequest: this.#requests.activity(),
+                progress: options.progress,
+                logger: this.#logger,
+                onDiagnostic: this.#options.onDiagnostic,
+                request: (method) => this.#request(method, {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }),
+                releaseTransport: (socket) => {
+                    this.#failAll(new HopperProcessError(null));
+                    if (socket !== undefined)
+                        this.#detachSocket(socket);
+                    socket?.destroy();
+                },
+            });
+        }
+        finally {
             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");
-            }
             this.#process = undefined;
             this.#launch = undefined;
-            const runtimeRoot = this.#runtimeRoot;
             this.#runtimeRoot = undefined;
-            await runtimeRoot?.close();
             this.#token = undefined;
-            this.#buffer = "";
+            this.#responses.reset();
             this.#launcherExitCode = undefined;
             this.#launcherFailureDiagnostic = undefined;
-        }
-        finally {
             this.#closing = false;
         }
     }
-    async #fallbackDocumentShutdown() {
-        const fallback = await this.#request("shutdown_document", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
-        if (!fallback.ok || !isHopperShutdownAcknowledgement(fallback.value))
-            this.#logger.warn({ status: fallback.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown fallback was not confirmed");
-    }
     async #connect(socketPath, deadline) {
         while (deadline.remainingMs() > 0) {
             if (deadline.signal.aborted)
@@ -306,17 +314,11 @@ export class HopperClient {
         const id = this.#nextId++;
         const startedAt = performance.now();
         const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs;
-        const response = this.#pending.wait(id, {
+        const result = await this.#requests.run(id, method, params, {
             timeoutMs,
             ...(options.signal === undefined ? {} : { signal: options.signal }),
-            timeoutValue: () => err(new HopperTimeoutError(timeoutMs)),
-            cancelledValue: () => err(new HopperCancelledError()),
+            ...(options.progress !== undefined ? { progress: options.progress } : {}),
         });
-        socket.write(`${JSON.stringify({ id, token, method, params })}\n`, (cause) => {
-            if (cause !== undefined && cause !== null)
-                this.#pending.settle(id, err(new HopperProcessError(null)));
-        });
-        const result = await response;
         this.#logger[result.ok ? "debug" : "warn"]({
             method,
             durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
@@ -331,6 +333,30 @@ export class HopperClient {
         socket.on("error", this.#onSocketError);
         socket.on("close", this.#onSocketClose);
     }
+    #acceptBridgeMessage(message) {
+        if (!("event" in message))
+            return this.#requests.accept(message.id, responseResult(message));
+        if (!this.#requests.acceptEvent(message))
+            return false;
+        this.#emitBridgeDiagnostic(message);
+        return true;
+    }
+    #emitBridgeDiagnostic(message) {
+        if (message.event.type !== "diagnostic")
+            return;
+        try {
+            this.#options.onDiagnostic?.({
+                type: "bridge-diagnostic",
+                request_id: message.id,
+                code: message.event.error.code,
+                category: message.event.error.type,
+                message: message.event.error.message,
+            });
+        }
+        catch {
+            this.#logger.warn({ requestId: message.id }, "Hopper bridge diagnostic consumer rejected an event");
+        }
+    }
     #detachSocket(socket) {
         socket.off("data", this.#onSocketData);
         socket.off("error", this.#onSocketError);
@@ -364,44 +390,12 @@ export class HopperClient {
         if (launch.ownsProcessLifetime && !this.#closing)
             this.#failAll(new HopperProcessError(event.code, this.#launcherFailureDiagnostic));
     }
-    #onData(chunk) {
-        this.#buffer += chunk;
-        let newline = this.#buffer.indexOf("\n");
-        while (newline >= 0) {
-            const line = this.#buffer.slice(0, newline).trim();
-            this.#buffer = this.#buffer.slice(newline + 1);
-            if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
-                this.#abortProtocol("Hopper response exceeded the maximum line size");
-                return;
-            }
-            if (line.length > 0)
-                this.#onLine(line);
-            newline = this.#buffer.indexOf("\n");
-        }
-        if (Buffer.byteLength(this.#buffer) > MAX_LINE_BYTES) {
-            this.#abortProtocol("Hopper response exceeded the maximum line size");
-        }
-    }
-    #onLine(line) {
-        const parsed = parseResponseLine(line);
-        if (!parsed.ok) {
-            this.#abortProtocol(parsed.error.message, parsed.error);
-            return;
-        }
-        if (!this.#pending.has(parsed.value.id)) {
-            if (parsed.value.id >= this.#nextId) {
-                this.#abortProtocol("Hopper returned an unknown response id");
-            }
-            return;
-        }
-        this.#pending.settle(parsed.value.id, responseResult(parsed.value));
-    }
     #abortProtocol(message, cause) {
         this.#failAll(new HopperProtocolError(message, { cause }));
         this.#socket?.destroy();
     }
     #failAll(error) {
-        this.#pending.failAll(() => err(error));
+        this.#requests.failAll(error);
     }
 }
 const isAborted = (signal) => signal?.aborted === true;

package/dist/hopper/HopperProvider.js

@@ -3,7 +3,7 @@ import { accessSync, constants } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
 import { err } from "../domain/result.js";
-import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
 import { hopperLoaderArgsForTarget, resolveHopperAnalysisProfile, } from "./HopperAnalysisProfile.js";
 import { HopperClient } from "./HopperClient.js";
@@ -24,36 +24,47 @@ const MUTATING_OPERATIONS = new Set([
 ]);
 /** Tool contracts implemented directly by the Hopper adapter. */
 export const HOPPER_PROVIDER_TOOL_CONTRACTS = Object.freeze([
-    ...OFFICIAL_TOOL_CONTRACTS,
-    ...ENHANCED_TOOL_CONTRACTS.filter((contract) => contract.name === "analyze_function"),
+    ...GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy"),
+    ...GENERATED_MCP_TOOL_CATALOG.filter(({ name }) => name === "analyze_function"),
 ]);
-const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
-    provider: IDENTITY,
-    operation: contract.name,
-    inputContractVersion: 1,
-    outputContractVersion: 1,
-    available: true,
-    reason: null,
-    pagination: "offset" in contract.inputSchema.shape ? "offset" : "none",
-    exhaustive: false,
-    effects: Object.freeze({
-        mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
-        launchesProcess: true,
-        mayShowUi: true,
-        mayAccessNetwork: false,
-        mayWriteFilesystem: MUTATING_OPERATIONS.has(contract.name),
-        changesPermissions: false,
-        requiresRoot: false,
-    }),
-    limits: Object.freeze({
-        maxResults: null,
-        maxPayloadBytes: null,
-        timeoutMs: null,
-    }),
-    limitations: Object.freeze([
-        "Results depend on Hopper's completed static analysis.",
-    ]),
-})));
+const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract) => {
+    const operation = contract.analysisOperation;
+    if (operation === null)
+        throw new TypeError(`Missing analysis operation for ${contract.name}`);
+    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,
+            mayShowUi: true,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: MUTATING_OPERATIONS.has(contract.name),
+            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;
@@ -178,6 +189,7 @@ export class HopperProvider {
             }),
             ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "bridge" }),
+            onDiagnostic: (diagnostic) => this.logger.info(diagnostic, "Hopper bridge reported a diagnostic"),
         });
         return {
             execute: async (operation, parameters, options) => {
@@ -200,6 +212,25 @@ export class HopperProvider {
                     ? []
                     : [{ provider: executionProvider, observation }];
             },
+            requestActivitySnapshots: () => {
+                const activity = client.requestActivity();
+                return [
+                    {
+                        provider: executionProvider,
+                        active: activity === null
+                            ? null
+                            : {
+                                requestId: activity.requestId,
+                                operation: activity.operation,
+                                elapsedMs: activity.elapsedMs,
+                                timeoutMs: activity.timeoutMs,
+                                callerState: activity.callerState,
+                            },
+                        queuedRequests: activity?.queuedRequests ?? 0,
+                    },
+                ];
+            },
+            closeWithOutcome: (options) => client.closeWithOutcome(options),
             close: () => client.close(),
         };
     }

package/dist/hopper/HopperRequestQueue.js

@@ -0,0 +1,215 @@
+import { performance } from "node:perf_hooks";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperTimeoutError, } from "../domain/errors.js";
+import { err } from "../domain/result.js";
+/** Bounded FIFO that keeps the wire serialized until Hopper actually replies. */
+export class HopperRequestQueue {
+    maximum;
+    send;
+    #queue = [];
+    #active;
+    constructor(maximum, send) {
+        this.maximum = maximum;
+        this.send = send;
+    }
+    /** Queue one request, counting queue wait against its caller deadline. */
+    run(id, method, params, options) {
+        if (options.signal?.aborted === true)
+            return Promise.resolve(err(new HopperCancelledError()));
+        if (options.timeoutMs <= 0)
+            return Promise.resolve(err(new HopperTimeoutError(options.timeoutMs)));
+        if (this.#size() >= this.maximum)
+            return Promise.resolve(err(new HopperProtocolError(`Hopper serial request queue reached its ${String(this.maximum)}-request limit`)));
+        return new Promise((resolve) => {
+            let entry;
+            const onAbort = options.signal === undefined ? undefined : () => this.#cancel(entry);
+            const timer = setTimeout(() => this.#timeout(entry), options.timeoutMs);
+            entry = {
+                id,
+                method,
+                params,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+                deadline: performance.now() + options.timeoutMs,
+                progress: options.progress,
+                resolve,
+                timer,
+                onAbort,
+                callerState: "waiting",
+                callerSettled: false,
+                startedAt: undefined,
+                heartbeat: undefined,
+            };
+            this.#queue.push(entry);
+            if (onAbort !== undefined)
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+            if (this.#active !== undefined || this.#queue.length > 1)
+                this.#report(entry, `${method} queued behind ${String(this.#size() - 1)} Hopper request(s)`);
+            this.#drain();
+        });
+    }
+    /** Settle the active wire request. False identifies an unexpected response id. */
+    accept(id, result) {
+        const entry = this.#active;
+        if (entry === undefined || entry.id !== id)
+            return false;
+        this.#releaseWire(entry);
+        if (!entry.callerSettled)
+            this.#settleCaller(entry, result, "waiting");
+        this.#active = undefined;
+        this.#drain();
+        return true;
+    }
+    /** Forward one correlated bridge event without releasing the wire request. */
+    acceptEvent(event) {
+        const entry = this.#active;
+        if (entry === undefined || entry.id !== event.id)
+            return false;
+        if (event.event.type === "progress" && !entry.callerSettled) {
+            if (event.event.terminal === true && entry.heartbeat !== undefined) {
+                clearInterval(entry.heartbeat);
+                entry.heartbeat = undefined;
+            }
+            this.#reportUpdate(entry, {
+                phase: event.event.phase,
+                completed: event.event.completed,
+                total: event.event.total,
+                message: event.event.message,
+                ...(event.event.terminal === undefined
+                    ? {}
+                    : { terminal: event.event.terminal }),
+            });
+        }
+        return true;
+    }
+    /** Fail the active wire request and every request still waiting in the FIFO. */
+    failAll(error) {
+        const active = this.#active;
+        this.#active = undefined;
+        if (active !== undefined) {
+            this.#releaseWire(active);
+            if (!active.callerSettled)
+                this.#settleCaller(active, err(error), "waiting");
+        }
+        for (const entry of this.#queue.splice(0))
+            this.#settleCaller(entry, err(error), "waiting");
+    }
+    /** Snapshot the one request still occupying Hopper's serial Python thread. */
+    activity() {
+        const active = this.#active;
+        if (active === undefined || active.startedAt === undefined)
+            return null;
+        return {
+            requestId: active.id,
+            operation: active.method,
+            elapsedMs: Math.max(0, Math.round(performance.now() - active.startedAt)),
+            timeoutMs: active.timeoutMs,
+            callerState: active.callerState,
+            queuedRequests: this.#queue.length,
+        };
+    }
+    /** Return whether an id belongs to a request that has not crossed the wire. */
+    hasQueued(id) {
+        return this.#queue.some((entry) => entry.id === id);
+    }
+    /** Number of caller requests waiting behind the active bridge operation. */
+    queuedCount() {
+        return this.#queue.length;
+    }
+    #size() {
+        return this.#queue.length + (this.#active === undefined ? 0 : 1);
+    }
+    #drain() {
+        if (this.#active !== undefined)
+            return;
+        const entry = this.#queue.shift();
+        if (entry === undefined)
+            return;
+        const remaining = entry.deadline - performance.now();
+        if (entry.signal?.aborted === true || remaining <= 0) {
+            this.#settleCaller(entry, entry.signal?.aborted === true
+                ? err(new HopperCancelledError())
+                : err(new HopperTimeoutError(entry.timeoutMs)), entry.signal?.aborted === true ? "cancelled" : "timed_out");
+            this.#drain();
+            return;
+        }
+        this.#active = entry;
+        entry.startedAt = performance.now();
+        this.#report(entry, `${entry.method} started on Hopper's serial bridge`);
+        entry.heartbeat = setInterval(() => {
+            if (entry.callerSettled || entry.startedAt === undefined)
+                return;
+            const elapsed = Math.round(performance.now() - entry.startedAt);
+            this.#report(entry, `${entry.method} is still running in Hopper (${String(elapsed)} ms elapsed)`);
+        }, 1_000);
+        try {
+            this.send({ id: entry.id, method: entry.method, params: entry.params }, () => this.accept(entry.id, err(new HopperProcessError(null))));
+        }
+        catch (cause) {
+            this.accept(entry.id, err(new HopperProtocolError("Hopper socket write failed", { cause })));
+        }
+    }
+    #timeout(entry) {
+        if (entry.callerSettled)
+            return;
+        if (this.#active === entry) {
+            this.#settleCaller(entry, err(new HopperTimeoutError(entry.timeoutMs)), "timed_out");
+            return;
+        }
+        const index = this.#queue.indexOf(entry);
+        if (index < 0)
+            return;
+        this.#queue.splice(index, 1);
+        this.#settleCaller(entry, err(new HopperTimeoutError(entry.timeoutMs)), "timed_out");
+    }
+    #cancel(entry) {
+        if (entry.callerSettled)
+            return;
+        if (this.#active === entry) {
+            this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+            return;
+        }
+        const index = this.#queue.indexOf(entry);
+        if (index < 0)
+            return;
+        this.#queue.splice(index, 1);
+        this.#settleCaller(entry, err(new HopperCancelledError()), "cancelled");
+    }
+    #settleCaller(entry, result, callerState) {
+        if (entry.callerSettled)
+            return;
+        entry.callerSettled = true;
+        entry.callerState = callerState;
+        if (this.#active === entry && entry.heartbeat !== undefined) {
+            clearInterval(entry.heartbeat);
+            entry.heartbeat = undefined;
+        }
+        clearTimeout(entry.timer);
+        if (entry.signal !== undefined && entry.onAbort !== undefined)
+            entry.signal.removeEventListener("abort", entry.onAbort);
+        entry.resolve(result);
+    }
+    #releaseWire(entry) {
+        if (entry.heartbeat !== undefined)
+            clearInterval(entry.heartbeat);
+        entry.heartbeat = undefined;
+        clearTimeout(entry.timer);
+        if (entry.signal !== undefined && entry.onAbort !== undefined)
+            entry.signal.removeEventListener("abort", entry.onAbort);
+    }
+    #report(entry, message) {
+        this.#reportUpdate(entry, {
+            phase: "hopper_request",
+            completed: 0,
+            total: 1,
+            message,
+        });
+    }
+    #reportUpdate(entry, update) {
+        try {
+            void Promise.resolve(entry.progress?.report(update)).catch(() => undefined);
+        }
+        catch {
+            // Progress observation cannot change the request outcome.
+        }
+    }
+}