rea-agents 6.4.0 → 6.7.0

package/dist/cutter/CutterBridgeClient.js

@@ -0,0 +1,760 @@
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { withArtifactRegularFile, ArtifactFileCleanupFailure, bindArtifactFileCleanup, artifactFileCancellationCause, assertArtifactReadActive, } from "../artifacts/ArtifactFileOperation.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { randomUUID } from "node:crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createConnection } from "node:net";
+import { lstat, opendir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { AnalysisCapabilityUnavailableError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { err, ok } from "../domain/result.js";
+import { requireWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
+const descriptorSchema = z.object({
+    session_id: z.string().uuid(),
+    pid: z.number().int().positive(),
+    host: z.literal("127.0.0.1"),
+    port: z.number().int().min(1).max(65535),
+    token: z.string().min(20),
+    document_generation: z.number().int().nonnegative(),
+    current_file: z.string().nullable(),
+    cutter_version: z.string().nullable(),
+    identity_status: z.literal("partial"),
+});
+export const CUTTER_PROVIDER_IDENTITY = {
+    id: "cutter.python-plugin",
+    name: "Cutter Python plugin",
+    version: null,
+};
+const responseSchema = z.object({
+    ok: z.boolean(),
+    session_id: z.string().uuid().optional(),
+    output: z.unknown().optional(),
+    current_file: z.string().nullable().optional(),
+    cutter_version: z.string().nullable().optional(),
+    document_generation: z.number().int().nonnegative().optional(),
+    identity_status: z.literal("partial").optional(),
+    error: z.string().optional(),
+    message: z.string().optional(),
+    execution_state: z
+        .enum(["not_started", "running", "complete", "failed", "unknown"])
+        .optional(),
+    output_truncated: z.boolean().optional(),
+    completed_commands: z
+        .array(z.object({
+        request_id: z.string().uuid(),
+        execution_state: z.enum(["not_started", "complete", "failed"]),
+    }))
+        .max(64)
+        .optional(),
+    completed_connection: z
+        .string()
+        .regex(/^[0-9a-f]{16}$/)
+        .optional(),
+});
+const acknowledgementSchema = z.object({
+    ok: z.literal(true),
+    acknowledged: z.boolean(),
+});
+const MAX_DESCRIPTOR_BYTES = 64 * 1024;
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+const FRAME_PAGE_BYTES = 64 * 1024;
+// Bound admitted descriptor input bytes and concurrent file/socket handles.
+const MAX_DESCRIPTOR_CANDIDATES = MAX_FRAME_BYTES / MAX_DESCRIPTOR_BYTES;
+const DISCOVERY_CONCURRENCY = 8;
+const serializeRequest = (descriptor, request) => {
+    const requestBytes = JSON.stringify({
+        ...request,
+        session_id: descriptor.session_id,
+    });
+    let frameBytes = Buffer.byteLength(JSON.stringify({ request: "", proof: "0".repeat(64) })) +
+        Buffer.byteLength(requestBytes);
+    for (const character of requestBytes)
+        if (character === '"' || character === "\\")
+            frameBytes += 1;
+    if (frameBytes > MAX_FRAME_BYTES)
+        throw new AnalysisResourceConstraintError("cutter_command", "transport", "Cutter request exceeds its authenticated frame limit; no command was sent.", { frame_bytes: frameBytes, max_frame_bytes: MAX_FRAME_BYTES });
+    return requestBytes;
+};
+class CutterBridgeResponseFrames {
+    #parts = [];
+    #page = Buffer.allocUnsafe(FRAME_PAGE_BYTES);
+    #pageLength = 0;
+    #contentBytes = 0;
+    #framesRead = 0;
+    push(chunk, onFrame) {
+        let offset = 0;
+        while (offset < chunk.length) {
+            const delimiter = chunk.indexOf(0x0a, offset);
+            const end = delimiter < 0 ? chunk.length : delimiter;
+            const segment = chunk.subarray(offset, end);
+            if (this.#contentBytes + segment.length + (delimiter < 0 ? 1 : 0) >
+                MAX_FRAME_BYTES)
+                throw new Error("Cutter bridge response exceeded its framed transport limit");
+            this.#append(segment);
+            if (delimiter < 0)
+                return;
+            if (++this.#contentBytes > MAX_FRAME_BYTES)
+                throw new Error("Cutter bridge response exceeded its framed transport limit");
+            if (this.#pageLength > 0)
+                this.#parts.push(this.#page.subarray(0, this.#pageLength));
+            const line = Buffer.concat(this.#parts, this.#contentBytes - 1);
+            this.#reset();
+            if (++this.#framesRead > 2)
+                throw new Error("Cutter bridge sent more than two protocol frames");
+            offset = delimiter + 1;
+            if (!onFrame(line))
+                return;
+        }
+    }
+    #append(segment) {
+        let copied = 0;
+        while (copied < segment.length) {
+            const length = Math.min(segment.length - copied, FRAME_PAGE_BYTES - this.#pageLength);
+            segment.copy(this.#page, this.#pageLength, copied, copied + length);
+            this.#pageLength += length;
+            this.#contentBytes += length;
+            copied += length;
+            if (this.#pageLength === FRAME_PAGE_BYTES) {
+                this.#parts.push(this.#page);
+                this.#page = Buffer.allocUnsafe(FRAME_PAGE_BYTES);
+                this.#pageLength = 0;
+            }
+        }
+    }
+    #reset() {
+        this.#parts = [];
+        this.#page = Buffer.allocUnsafe(FRAME_PAGE_BYTES);
+        this.#pageLength = 0;
+        this.#contentBytes = 0;
+    }
+}
+const assertCommandActive = (signal) => {
+    if (signal?.aborted)
+        throw new AnalysisCancelledError("cutter_command", {
+            cause: signal.reason,
+        });
+};
+const mapDiscovery = async (inputs, operation, signal) => {
+    signal?.throwIfAborted();
+    const results = new Array(inputs.length);
+    let next = 0;
+    let stopped = false;
+    const workers = await Promise.allSettled(Array.from({ length: Math.min(inputs.length, DISCOVERY_CONCURRENCY) }, async () => {
+        try {
+            while (!stopped && next < inputs.length) {
+                signal?.throwIfAborted();
+                const index = next++;
+                results[index] = await operation(inputs[index]);
+            }
+        }
+        catch (cause) {
+            stopped = true;
+            throw cause;
+        }
+    }));
+    const failures = workers.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (failures.length > 1)
+        throw new CutterDiscoveryFailure(failures);
+    if (failures.length === 1)
+        throw failures[0];
+    signal?.throwIfAborted();
+    return results;
+};
+class CutterBridgeRequestFailure extends Error {
+    requestSent;
+    constructor(message, requestSent) {
+        super(message);
+        this.requestSent = requestSent;
+    }
+}
+/** Discovers and communicates with REA Python bridge plugins in live Cutter processes. */
+export class CutterBridgeClient {
+    #directory;
+    #descriptorResources = new ArtifactResourceScope();
+    #platform;
+    #windowsPrivateReader;
+    #pendingAcknowledgements = new Map();
+    constructor(environment = process.env, options = {}) {
+        const configured = environment.REA_CUTTER_BRIDGE_DIR;
+        const localAppData = environment.LOCALAPPDATA;
+        this.#platform = options.platform ?? process.platform;
+        this.#windowsPrivateReader =
+            options.windowsPrivateReader ??
+                (this.#platform === "win32"
+                    ? {
+                        verifyDirectory: (directory) => z
+                            .object({ privateDacl: z.literal(true) })
+                            .safeParse(requireWindowsNativeAuthority().call("cutter_bridge_verify_directory", [directory])).success,
+                        readDescriptor: (directory, name, maxBytes) => z
+                            .instanceof(Buffer)
+                            .parse(requireWindowsNativeAuthority().call("cutter_bridge_read_descriptor", [directory, name, maxBytes])),
+                    }
+                    : undefined);
+        this.#directory = resolveBridgeDirectory(configured, this.#platform, localAppData, homeDirectoryFromEnvironment(environment, this.#platform));
+    }
+    async retryDescriptorCleanup() {
+        try {
+            await this.#descriptorResources.retryCleanup();
+        }
+        catch (cause) {
+            throw descriptorFailure(cause, "close_cutter_descriptors");
+        }
+    }
+    async close() {
+        try {
+            await this.#descriptorResources.close();
+        }
+        catch (cause) {
+            throw descriptorFailure(cause, "close_cutter_descriptors");
+        }
+    }
+    async listSessions(options = {}) {
+        const { signal } = options;
+        const loaded = await this.#readDescriptors("list_cutter_sessions", signal);
+        if (loaded.error !== undefined)
+            return {
+                sessions: [],
+                bridge_directory: this.#directory,
+                discovery_status: loaded.error,
+                bridge_directory_security: loaded.security,
+            };
+        const descriptors = await mapDiscovery(loaded.descriptors, async (descriptor) => {
+            if (options.signal?.aborted)
+                throw new AnalysisCancelledError("list_cutter_sessions", {
+                    cause: options.signal.reason,
+                });
+            try {
+                const status = responseSchema.safeParse(await this.#request(descriptor, serializeRequest(descriptor, {
+                    kind: "status",
+                    session_id: descriptor.session_id,
+                }), signal));
+                if (!status.success ||
+                    !status.data.ok ||
+                    status.data.session_id !== descriptor.session_id)
+                    return undefined;
+                return {
+                    session_id: descriptor.session_id,
+                    pid: descriptor.pid,
+                    document_generation: status.data.document_generation ?? descriptor.document_generation,
+                    current_file: status.data.current_file === undefined
+                        ? descriptor.current_file
+                        : status.data.current_file,
+                    cutter_version: status.data.cutter_version ?? descriptor.cutter_version,
+                    identity_status: "partial",
+                };
+            }
+            catch {
+                signal?.throwIfAborted();
+                return undefined;
+            }
+        }, signal);
+        if (options.signal?.aborted)
+            throw new AnalysisCancelledError("list_cutter_sessions", {
+                cause: options.signal.reason,
+            });
+        const sessions = descriptors.filter((value) => value !== undefined);
+        return {
+            sessions,
+            bridge_directory: this.#directory,
+            discovery_status: sessions.length > 0 ? "sessions_found" : "no_live_bridge_found",
+            bridge_directory_security: loaded.security,
+        };
+    }
+    async execute(input) {
+        assertCommandActive(input.signal);
+        const descriptor = await this.#find(input.sessionId, input.signal);
+        assertCommandActive(input.signal);
+        const requestId = randomUUID();
+        const commandRequest = serializeRequest(descriptor, {
+            kind: "command",
+            request_id: requestId,
+            expected_generation: input.expectedGeneration,
+            command: input.command,
+            json: input.json,
+        });
+        await this.#recoverCompletedCommands(descriptor, input.signal);
+        await this.#retryPendingAcknowledgements(descriptor);
+        assertCommandActive(input.signal);
+        let completionToken;
+        let rawResponse;
+        try {
+            rawResponse = await this.#request(descriptor, commandRequest, input.signal, (ordinal) => {
+                completionToken = ordinal;
+            });
+        }
+        catch (cause) {
+            if (!(cause instanceof CutterBridgeRequestFailure) || !cause.requestSent)
+                throw cause;
+            return {
+                requestId,
+                output: null,
+                currentFile: descriptor.current_file,
+                documentGeneration: input.expectedGeneration,
+                identityStatus: "partial",
+                cutterVersion: descriptor.cutter_version,
+                executionState: "unknown",
+                error: "transport-response-missing",
+                message: `${cause.message}; the command may have completed; do not retry automatically`,
+                outputTruncated: false,
+                ...(completionToken === undefined ? {} : { completionToken }),
+            };
+        }
+        const parsed = responseSchema.safeParse(rawResponse);
+        if (!parsed.success)
+            return {
+                requestId,
+                output: null,
+                currentFile: descriptor.current_file,
+                documentGeneration: input.expectedGeneration,
+                identityStatus: "partial",
+                cutterVersion: descriptor.cutter_version,
+                executionState: "unknown",
+                error: "malformed-bridge-response",
+                message: "Cutter may have completed the command, but its response was invalid; do not retry automatically",
+                outputTruncated: false,
+                ...(completionToken === undefined ? {} : { completionToken }),
+            };
+        const response = parsed.data;
+        const executionState = response.ok
+            ? response.execution_state === undefined ||
+                response.execution_state === "complete"
+                ? "complete"
+                : response.execution_state === "not_started"
+                    ? "not_started"
+                    : "unknown"
+            : response.execution_state === "failed"
+                ? "failed"
+                : response.execution_state === "not_started"
+                    ? "not_started"
+                    : "unknown";
+        if (executionState !== "unknown")
+            await this.#acknowledgeCompletion(descriptor, requestId);
+        if (response.error === "active-document-generation-changed")
+            throw new Error("Cutter's active document generation changed. List sessions again and select the current generation.");
+        return {
+            requestId,
+            output: response.output ?? null,
+            currentFile: response.current_file === undefined
+                ? descriptor.current_file
+                : response.current_file,
+            documentGeneration: response.document_generation ?? input.expectedGeneration,
+            identityStatus: "partial",
+            cutterVersion: response.cutter_version ?? descriptor.cutter_version,
+            executionState,
+            error: response.ok ? null : (response.error ?? "cutter-command-failed"),
+            message: response.message ?? null,
+            outputTruncated: response.output_truncated ?? false,
+            ...(completionToken === undefined ? {} : { completionToken }),
+        };
+    }
+    /** Confirm completion by exact receipt or authenticated connection watermark. */
+    async confirmCommandCompletion(sessionId, requestId, completionToken) {
+        let descriptor;
+        try {
+            descriptor = await this.#find(sessionId);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            return err(new AnalysisCapabilityUnavailableError("cutter", "cutter_command", cause instanceof Error ? cause.message : "Cutter session unavailable", { cause }));
+        }
+        try {
+            const status = await this.#readCommandStatus(descriptor);
+            const completed = (status.completed_commands ?? []).some((receipt) => receipt.request_id === requestId);
+            if (completed)
+                await this.#acknowledgeCompletion(descriptor, requestId);
+            return ok(completed ||
+                (completionToken !== undefined &&
+                    status.completed_connection !== undefined &&
+                    status.completed_connection >= completionToken));
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            return err(new AnalysisCapabilityUnavailableError("cutter", "cutter_command", cause instanceof Error ? cause.message : "Cutter status failed", { cause, diagnostics: { auxiliary_operation: "status" } }));
+        }
+    }
+    async #readCommandStatus(descriptor, signal) {
+        const raw = await this.#request(descriptor, serializeRequest(descriptor, {
+            kind: "status",
+            session_id: descriptor.session_id,
+        }), signal);
+        const status = responseSchema.safeParse(raw);
+        if (!status.success ||
+            !status.data.ok ||
+            status.data.session_id !== descriptor.session_id)
+            throw new AnalysisOutputError("cutter_command", "The bridge status response did not contain a valid session identity.", {
+                cause: status.success ? undefined : status.error,
+                diagnostics: { auxiliary_operation: "status" },
+            });
+        return status.data;
+    }
+    async #recoverCompletedCommands(descriptor, signal) {
+        const status = await this.#readCommandStatus(descriptor, signal);
+        if (status.completed_connection === undefined)
+            throw new AnalysisOutputError("cutter_command", "The bridge did not provide authenticated proof that earlier connections reached a terminal state.", { diagnostics: { auxiliary_operation: "status" } });
+        const pending = this.#pendingAcknowledgements.get(descriptor.session_id) ?? new Set();
+        for (const receipt of status.completed_commands ?? [])
+            pending.add(receipt.request_id);
+        if (pending.size > 0)
+            this.#pendingAcknowledgements.set(descriptor.session_id, pending);
+    }
+    async #acknowledgeCompletion(descriptor, requestId) {
+        try {
+            const raw = await this.#request(descriptor, serializeRequest(descriptor, {
+                kind: "ack",
+                request_id: requestId,
+            }));
+            const acknowledged = acknowledgementSchema.safeParse(raw);
+            if (!acknowledged.success)
+                throw new Error("Cutter did not confirm the completion receipt acknowledgement.");
+            const pending = this.#pendingAcknowledgements.get(descriptor.session_id);
+            pending?.delete(requestId);
+            if (pending?.size === 0)
+                this.#pendingAcknowledgements.delete(descriptor.session_id);
+            return true;
+        }
+        catch {
+            const pending = this.#pendingAcknowledgements.get(descriptor.session_id) ??
+                new Set();
+            pending.add(requestId);
+            this.#pendingAcknowledgements.set(descriptor.session_id, pending);
+            return false;
+        }
+    }
+    async #retryPendingAcknowledgements(descriptor) {
+        const pending = this.#pendingAcknowledgements.get(descriptor.session_id);
+        if (pending === undefined)
+            return;
+        for (const requestId of pending) {
+            if (!(await this.#acknowledgeCompletion(descriptor, requestId)))
+                throw new AnalysisCapabilityUnavailableError("cutter", "cutter_command", "A retained Cutter completion receipt could not be acknowledged; no new command was sent.");
+        }
+    }
+    async #find(sessionId, signal) {
+        const loaded = await this.#readDescriptors("cutter_command", signal);
+        if (loaded.error === "bridge_directory_capacity_exceeded")
+            throw new AnalysisResourceConstraintError("cutter_command", "transport", "Cutter descriptor discovery exceeded its candidate budget; no command was sent.", {
+                max_descriptor_candidates: MAX_DESCRIPTOR_CANDIDATES,
+                bridge_directory: this.#directory,
+            });
+        if (loaded.error !== undefined)
+            throw new AnalysisCapabilityUnavailableError("cutter", "cutter_command", `Cutter descriptor discovery failed: ${loaded.error}`);
+        const descriptor = loaded.descriptors.find((candidate) => candidate.session_id === sessionId);
+        if (descriptor === undefined)
+            throw new Error("Cutter bridge session is unavailable or stale");
+        return descriptor;
+    }
+    async listDescriptors() {
+        const loaded = await this.#readDescriptors("list_cutter_sessions");
+        return loaded.descriptors;
+    }
+    async #readDescriptors(operation, signal) {
+        try {
+            return await this.#descriptorResources.run(() => this.#loadDescriptors(signal));
+        }
+        catch (cause) {
+            throw descriptorFailure(cause, operation);
+        }
+    }
+    async #loadDescriptors(signal) {
+        assertArtifactReadActive(signal);
+        let directoryInfo;
+        try {
+            directoryInfo = await lstat(this.#directory);
+        }
+        catch (cause) {
+            const code = cause.code;
+            if (code === "ENOENT")
+                return { descriptors: [], security: "not_checked" };
+            return {
+                descriptors: [],
+                security: "not_checked",
+                error: "bridge_directory_unavailable",
+            };
+        }
+        if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink())
+            return {
+                descriptors: [],
+                security: "not_private",
+                error: "bridge_directory_insecure",
+            };
+        const currentUid = this.#platform !== "win32" ? process.getuid?.() : undefined;
+        const posix = currentUid !== undefined;
+        if (posix &&
+            (directoryInfo.uid !== currentUid || (directoryInfo.mode & 0o077) !== 0))
+            return {
+                descriptors: [],
+                security: "not_private",
+                error: "bridge_directory_insecure",
+            };
+        let security = posix
+            ? "private_verified"
+            : "unverified_platform_acl";
+        const windowsPrivateReader = this.#windowsPrivateReader;
+        if (!posix) {
+            if (this.#platform !== "win32" || windowsPrivateReader === undefined)
+                return {
+                    descriptors: [],
+                    security,
+                    error: "bridge_directory_insecure",
+                };
+            try {
+                if (!windowsPrivateReader.verifyDirectory(this.#directory))
+                    return {
+                        descriptors: [],
+                        security: "not_private",
+                        error: "bridge_directory_insecure",
+                    };
+                security = "private_verified";
+            }
+            catch {
+                return {
+                    descriptors: [],
+                    security,
+                    error: "bridge_directory_insecure",
+                };
+            }
+        }
+        const entries = [];
+        try {
+            const directory = await opendir(this.#directory);
+            for await (const entry of directory) {
+                assertArtifactReadActive(signal);
+                if (!/^cutter-\d+-[0-9a-f-]{36}\.json$/iu.test(entry.name))
+                    continue;
+                if (entries.length === MAX_DESCRIPTOR_CANDIDATES)
+                    return {
+                        descriptors: [],
+                        security,
+                        error: "bridge_directory_capacity_exceeded",
+                    };
+                entries.push(entry.name);
+            }
+        }
+        catch (cause) {
+            if (cause instanceof ArtifactReaderFailure &&
+                cause.reason === "cancelled")
+                throw cause;
+            return {
+                descriptors: [],
+                security: "not_checked",
+                error: "bridge_directory_unavailable",
+            };
+        }
+        const loaded = await mapDiscovery(entries, async (entry) => {
+            assertArtifactReadActive(signal);
+            try {
+                let bytes;
+                if (this.#platform === "win32") {
+                    bytes = windowsPrivateReader.readDescriptor(this.#directory, entry, MAX_DESCRIPTOR_BYTES);
+                }
+                else {
+                    const boundedBytes = await withArtifactRegularFile(join(this.#directory, entry), this.#descriptorResources, signal, async (file) => {
+                        const info = await file.stat();
+                        if (info.size > MAX_DESCRIPTOR_BYTES ||
+                            info.uid !== currentUid ||
+                            (info.mode & 0o077) !== 0)
+                            return undefined;
+                        assertArtifactReadActive(signal);
+                        const bytes = await readBoundedFileBytes(file, MAX_DESCRIPTOR_BYTES);
+                        assertArtifactReadActive(signal);
+                        return bytes;
+                    });
+                    if (boundedBytes === undefined)
+                        return undefined;
+                    bytes = boundedBytes;
+                }
+                assertArtifactReadActive(signal);
+                if (bytes.byteLength > MAX_DESCRIPTOR_BYTES)
+                    return undefined;
+                const parsed = descriptorSchema.safeParse(JSON.parse(bytes.toString("utf8")));
+                if (!parsed.success ||
+                    entry !== `cutter-${parsed.data.pid}-${parsed.data.session_id}.json`)
+                    return undefined;
+                return parsed.data;
+            }
+            catch (cause) {
+                if (cause instanceof ArtifactReaderFailure &&
+                    (cause.cleanup !== undefined || cause.reason === "cancelled"))
+                    throw cause;
+                return undefined;
+            }
+        });
+        assertArtifactReadActive(signal);
+        return {
+            descriptors: loaded.filter((value) => value !== undefined),
+            security,
+        };
+    }
+    #request(descriptor, requestBytes, signal, onAuthenticated) {
+        return new Promise((resolve, reject) => {
+            const connection = createConnection({
+                host: descriptor.host,
+                port: descriptor.port,
+            });
+            const frames = new CutterBridgeResponseFrames();
+            let completion;
+            let requestSent = false;
+            let authenticated = false;
+            const clientNonce = randomBytes(32).toString("hex");
+            let serverNonce = "";
+            let connectionOrdinal;
+            const finish = (complete) => {
+                if (completion !== undefined)
+                    return;
+                completion = complete;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                // Retain this request until its owned socket has actually closed.
+                connection.destroy();
+            };
+            const rejectRequest = (message) => finish(() => reject(new CutterBridgeRequestFailure(message, requestSent)));
+            const timer = setTimeout(() => {
+                rejectRequest("Cutter bridge request timed out");
+            }, 25_000);
+            const onAbort = () => {
+                rejectRequest("Cutter bridge request was cancelled");
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+            connection.once("connect", () => {
+                if (completion !== undefined)
+                    return;
+                connection.write(`${JSON.stringify({ kind: "rea-auth-v2", nonce: clientNonce })}\n`);
+            });
+            connection.on("data", (chunk) => {
+                if (completion !== undefined)
+                    return;
+                try {
+                    frames.push(chunk, (line) => {
+                        const frame = JSON.parse(line.toString("utf8"));
+                        if (!authenticated) {
+                            const challenge = z
+                                .object({
+                                session_id: z.string().uuid(),
+                                nonce: z.string().regex(/^[0-9a-f]{64}$/),
+                                proof: z.string().regex(/^[0-9a-f]{64}$/),
+                            })
+                                .parse(frame);
+                            if (challenge.session_id !== descriptor.session_id)
+                                throw new Error("unexpected peer session");
+                            serverNonce = challenge.nonce;
+                            connectionOrdinal = challenge.nonce.slice(0, 16);
+                            const expected = createHmac("sha256", descriptor.token)
+                                .update(`rea-cutter-server-v2:${descriptor.session_id}:${clientNonce}:${challenge.nonce}`)
+                                .digest();
+                            if (!timingSafeEqual(expected, Buffer.from(challenge.proof, "hex")))
+                                throw new Error("peer proof failed");
+                            onAuthenticated?.(connectionOrdinal);
+                            const proof = createHmac("sha256", descriptor.token)
+                                .update(`rea-cutter-client-v2:${descriptor.session_id}:${clientNonce}:${challenge.nonce}:${requestBytes}`)
+                                .digest("hex");
+                            authenticated = true;
+                            requestSent = true;
+                            connection.write(`${JSON.stringify({ request: requestBytes, proof })}\n`);
+                            return true;
+                        }
+                        else {
+                            const envelope = z
+                                .object({
+                                response: z.string(),
+                                proof: z.string().regex(/^[0-9a-f]{64}$/),
+                            })
+                                .parse(frame);
+                            const expected = createHmac("sha256", descriptor.token)
+                                .update(`rea-cutter-response-v2:${descriptor.session_id}:${clientNonce}:${serverNonce}:${envelope.response}`)
+                                .digest();
+                            if (!timingSafeEqual(expected, Buffer.from(envelope.proof, "hex")))
+                                throw new Error("response proof failed");
+                            const response = JSON.parse(envelope.response);
+                            finish(() => resolve(response));
+                            return false;
+                        }
+                    });
+                }
+                catch {
+                    rejectRequest("Cutter bridge peer authentication or response failed");
+                }
+            });
+            connection.once("error", (cause) => rejectRequest(`Cutter bridge is unavailable: ${cause.message}`));
+            connection.once("close", () => {
+                rejectRequest("Cutter bridge closed before returning a complete response");
+                completion?.();
+            });
+        });
+    }
+}
+const resolveBridgeDirectory = (configured, platform, localAppData, homeDirectory) => {
+    if (configured !== undefined && configured !== "") {
+        if (configured === "~")
+            return homeDirectory;
+        if (configured.startsWith("~/"))
+            return join(homeDirectory, configured.slice(2));
+        if (platform === "win32" && configured.startsWith("~\\"))
+            return join(homeDirectory, configured.slice(2));
+        return configured;
+    }
+    return platform === "win32" && localAppData
+        ? join(localAppData, "REA", "CutterBridge")
+        : join(homeDirectory, ".cache", "rea", "cutter-bridge");
+};
+class CutterDiscoveryFailure extends Error {
+    failures;
+    constructor(failures) {
+        super("Cutter discovery workers failed");
+        this.failures = failures;
+    }
+}
+const descriptorFailure = (cause, operation) => {
+    if (cause instanceof CutterDiscoveryFailure) {
+        const failures = cause.failures.map((failure) => {
+            const parsed = descriptorFailure(failure, operation);
+            return parsed instanceof AnalysisError
+                ? parsed
+                : new ProviderAdapterError("cutter", operation, { cause: parsed });
+        });
+        const cleanup = failures.filter((failure) => failure.cleanupIncomplete);
+        if (cleanup.length === 0)
+            return failures[0];
+        return new ProviderCleanupError("cutter", cleanup.flatMap((failure) => failure.cleanupResources), { reason: "Cutter descriptor discovery failed with unconfirmed closes" }, { operation, cause: new AggregateError(failures, cause.message) }).bindCleanupDependencies(cleanup);
+    }
+    if (!(cause instanceof ArtifactReaderFailure))
+        return cause;
+    if (cause.cleanup !== undefined) {
+        const cleanup = new ProviderCleanupError("cutter", cause.cleanup.resources, { reason: cause.cleanup.reason }, { operation, cause });
+        bindArtifactFileCleanup(cause, cleanup);
+        const outcome = cause instanceof ArtifactFileCleanupFailure
+            ? cause.fileCleanupFailure.outcome
+            : undefined;
+        const primary = outcome?.kind === "failed"
+            ? descriptorFailure(outcome.cause, operation)
+            : outcome?.kind === "completed" &&
+                cause instanceof ArtifactFileCleanupFailure &&
+                cause.fileCleanupFailure.completionCancellation !== undefined
+                ? new AnalysisCancelledError(operation, {
+                    cause: cause.fileCleanupFailure.completionCancellation.reason,
+                })
+                : undefined;
+        if (primary === undefined && outcome?.kind !== "failed")
+            return cleanup;
+        const original = primary instanceof AnalysisError
+            ? primary
+            : new ProviderAdapterError("cutter", operation, { cause: primary });
+        return analysisErrorWithCleanupFailure(original, cleanup, operation).bindCleanupDependencies([cleanup]);
+    }
+    if (cause.reason === "cancelled")
+        return new AnalysisCancelledError(operation, {
+            cause: artifactFileCancellationCause(cause),
+        });
+    return cause;
+};