@tangle-network/agent-eval 0.137.0 → 0.139.0

package/dist/single-run-lock-BTTtPZ9N.js

@@ -0,0 +1,989 @@
+import { c as ValidationError } from "./errors-D-LKuDhb.js";
+import { c as costForTokenPricing, i as CostLedger } from "./cost-ledger-CZ9diLxY.js";
+import { a as appendLedgerLine, d as tryAcquireAtomicFileLock, o as tryWithLedgerFileLock, u as probeAtomicFileLock } from "./ledger-core-Dxz0Rkwa.js";
+import { createRequire } from "node:module";
+import { isAbsolute, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { lstat, mkdtemp, open, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+//#region src/campaign/external-optimizer-contracts.ts
+const MAX_TIMER_DELAY_MS$1 = 2147483647;
+function isCandidateText(value, maxChars) {
+	return typeof value === "string" && value.trim().length > 0 && value.length <= maxChars;
+}
+function isExternalTextCandidate(value) {
+	if (typeof value === "string") return value.trim().length > 0;
+	if (!isRecord(value)) return false;
+	const entries = Object.entries(value);
+	return entries.length > 0 && entries.every(([name, content]) => name.trim().length > 0 && name.trim() === name && typeof content === "string");
+}
+function assertJsonValue(value, label, seen = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number" && Number.isFinite(value)) return;
+	if (Array.isArray(value)) {
+		if (seen.has(value)) throw new Error(`${label} must be JSON-serializable`);
+		seen.add(value);
+		for (const item of value) assertJsonValue(item, label, seen);
+		seen.delete(value);
+		return;
+	}
+	if (typeof value === "object") {
+		if (seen.has(value)) throw new Error(`${label} must be JSON-serializable`);
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw new Error(`${label} must be JSON-serializable`);
+		seen.add(value);
+		for (const item of Object.values(value)) assertJsonValue(item, label, seen);
+		seen.delete(value);
+		return;
+	}
+	throw new Error(`${label} must be JSON-serializable`);
+}
+function assertNoCredentialValues(value, path, credentialLocation = "runner.env") {
+	if (Array.isArray(value)) {
+		for (const [index, item] of value.entries()) assertNoCredentialValues(item, `${path}[${index}]`, credentialLocation);
+		return;
+	}
+	if (!isRecord(value)) return;
+	for (const [key, item] of Object.entries(value)) {
+		if (isCredentialKey(key)) throw new Error(`${path}.${key} must be supplied through ${credentialLocation}`);
+		assertNoCredentialValues(item, `${path}.${key}`, credentialLocation);
+	}
+}
+function removeCredentialEnvironment(environment) {
+	const sanitized = {};
+	for (const [key, value] of Object.entries(environment)) if (value !== void 0 && !isCredentialKey(key)) sanitized[key] = value;
+	return sanitized;
+}
+function assertExternalOptimizerModelBudget(value, label) {
+	if (!value || typeof value !== "object") throw new Error(`${label} is required`);
+	for (const [field, entry] of [
+		["maxRequests", value.maxRequests],
+		["maxRequestBytes", value.maxRequestBytes],
+		["maxResponseBytes", value.maxResponseBytes],
+		["maxOutputTokensPerRequest", value.maxOutputTokensPerRequest]
+	]) if (!Number.isSafeInteger(entry) || entry <= 0) throw new Error(`${label}.${field} must be a positive safe integer`);
+	if (!Number.isFinite(value.maxCostUsd) || value.maxCostUsd <= 0) throw new Error(`${label}.maxCostUsd must be positive and finite`);
+	if (value.requestTimeoutMs !== void 0 && (!Number.isSafeInteger(value.requestTimeoutMs) || value.requestTimeoutMs <= 0 || value.requestTimeoutMs > MAX_TIMER_DELAY_MS$1)) throw new Error(`${label}.requestTimeoutMs must be between 1 and ${MAX_TIMER_DELAY_MS$1}`);
+	costForTokenPricing(value.pricing, {
+		inputTokens: 1,
+		outputTokens: 1
+	});
+}
+function safePathComponent(value) {
+	return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function isCredentialKey(key) {
+	return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/-/g, "_").toLowerCase().split("_").some((segment) => [
+		"auth",
+		"authorization",
+		"cookie",
+		"credential",
+		"credentials",
+		"key",
+		"password",
+		"secret",
+		"session",
+		"token"
+	].includes(segment));
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/campaign/external-optimizer-http.ts
+function listenLocal(server) {
+	return new Promise((resolvePromise, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			server.off("error", reject);
+			const address = server.address();
+			if (!address || typeof address === "string") {
+				reject(/* @__PURE__ */ new Error("external optimizer callback did not bind a TCP port"));
+				return;
+			}
+			resolvePromise(address.port);
+		});
+	});
+}
+function closeServer(server) {
+	return new Promise((resolvePromise, reject) => {
+		server.close((error) => error ? reject(error) : resolvePromise());
+	});
+}
+function sendJson(response, status, body) {
+	response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	response.end(JSON.stringify(body));
+}
+//#endregion
+//#region src/campaign/external-optimizer-model-proxy.ts
+const MODEL_PROXY_PATHS = /* @__PURE__ */ new Set(["/v1/chat/completions", "/v1/responses"]);
+/**
+* Put an OpenAI-compatible optimizer behind the shared cost ledger.
+*
+* The child process receives only a loopback URL and an ephemeral token.
+* Provider credentials stay in this process. Every request reserves its
+* conservative byte-count input bound plus the provider-enforced output cap
+* before it leaves the machine.
+*/
+async function startExternalOptimizerModelProxy(args) {
+	assertModelProxyConfig(args);
+	args.signal?.throwIfAborted();
+	const token = randomLocalToken();
+	const fetchImpl = args.fetchImpl ?? fetch;
+	let requestCount = 0;
+	let successfulCompletionCount = 0;
+	let totalRequestCount = args.initialUsage?.requests ?? 0;
+	let committedForBudget = args.initialUsage?.costUsd ?? 0;
+	let reservedForBudget = 0;
+	let accepting = true;
+	let closePromise;
+	const activeControllers = /* @__PURE__ */ new Set();
+	const activeHandlers = /* @__PURE__ */ new Set();
+	const server = createServer((request, response) => {
+		if (!accepting) {
+			sendJsonIfOpen(response, 503, { error: "external optimizer model proxy is closing" });
+			return;
+		}
+		const controller = new AbortController();
+		const abortRequest = () => {
+			request.destroy();
+			response.destroy();
+		};
+		activeControllers.add(controller);
+		controller.signal.addEventListener("abort", abortRequest, { once: true });
+		let handler;
+		handler = handleModelProxyRequest({
+			request,
+			response,
+			controller,
+			token,
+			args,
+			fetchImpl,
+			nextReservation: (maximumCostUsd) => {
+				if (totalRequestCount >= args.budget.maxRequests) return {
+					accepted: false,
+					reason: "optimizer model request limit reached"
+				};
+				if (committedForBudget + reservedForBudget + maximumCostUsd > args.budget.maxCostUsd + Number.EPSILON) return {
+					accepted: false,
+					reason: "optimizer model cost limit reached"
+				};
+				requestCount += 1;
+				totalRequestCount += 1;
+				reservedForBudget += maximumCostUsd;
+				return { accepted: true };
+			},
+			settleReservation: (maximumCostUsd, chargedCostUsd) => {
+				reservedForBudget = Math.max(0, reservedForBudget - maximumCostUsd);
+				committedForBudget += chargedCostUsd;
+			},
+			recordSuccessfulCompletion: () => {
+				successfulCompletionCount += 1;
+			}
+		}).finally(() => {
+			controller.signal.removeEventListener("abort", abortRequest);
+			activeControllers.delete(controller);
+			activeHandlers.delete(handler);
+		});
+		activeHandlers.add(handler);
+		handler.catch(() => void 0);
+	});
+	const port = await listenLocal(server);
+	const close = () => {
+		closePromise ??= closeModelProxy();
+		return closePromise;
+	};
+	const onAbort = () => {
+		close().catch(() => void 0);
+	};
+	args.signal?.addEventListener("abort", onAbort, { once: true });
+	if (args.signal?.aborted) onAbort();
+	return {
+		baseUrl: `http://127.0.0.1:${port}/v1`,
+		apiKey: token,
+		requestAttempts: () => requestCount,
+		successfulCompletions: () => successfulCompletionCount,
+		close
+	};
+	async function closeModelProxy() {
+		args.signal?.removeEventListener("abort", onAbort);
+		accepting = false;
+		const closingServer = closeServer(server);
+		server.closeIdleConnections?.();
+		for (const controller of activeControllers) controller.abort();
+		const [serverResult] = await Promise.allSettled([closingServer, waitForActiveHandlers(activeHandlers)]);
+		if (activeControllers.size !== 0 || activeHandlers.size !== 0) throw new Error("external optimizer model proxy closed with active request work");
+		if (serverResult?.status === "rejected") throw serverResult.reason;
+	}
+}
+async function handleModelProxyRequest(args) {
+	const { controller, request, response } = args;
+	try {
+		const path = request.url ? new URL(request.url, "http://127.0.0.1").pathname : "";
+		if (request.method !== "POST" || !MODEL_PROXY_PATHS.has(path)) {
+			sendJsonIfOpen(response, 404, { error: "not found" });
+			return;
+		}
+		if (request.headers.authorization !== `Bearer ${args.token}`) {
+			sendJsonIfOpen(response, 401, { error: "unauthorized" });
+			return;
+		}
+		const body = await readBody(request, args.args.budget.maxRequestBytes);
+		const parsed = parseModelProxyRequest(body, args.args.model, args.args.budget);
+		const maximumUsage = conservativeMaximumUsage(body.byteLength, parsed.maxOutputTokens, args.args.budget.pricing);
+		const maximumCostUsd = costForTokenPricing(args.args.budget.pricing, maximumUsage);
+		const reservation = args.nextReservation(maximumCostUsd);
+		if (!reservation.accepted) {
+			sendJsonIfOpen(response, 429, { error: reservation.reason });
+			return;
+		}
+		const timeout = setTimeout(() => controller.abort(), args.args.budget.requestTimeoutMs ?? 3e5);
+		let chargedForBudget = maximumCostUsd;
+		try {
+			const paid = await args.args.costLedger.runPaidCall({
+				channel: args.args.channel ?? "optimizer",
+				phase: args.args.phase,
+				actor: args.args.actor,
+				...args.args.tags ? { tags: args.args.tags } : {},
+				model: args.args.model,
+				maximumCharge: {
+					customTokenPricing: args.args.budget.pricing,
+					...maximumUsage
+				},
+				execute: async () => forwardModelProxyRequest({
+					fetchImpl: args.fetchImpl,
+					upstreamBaseUrl: args.args.upstreamBaseUrl,
+					upstreamApiKey: args.args.upstreamApiKey,
+					path,
+					body,
+					model: args.args.model,
+					pricing: args.args.budget.pricing,
+					maxOutputTokens: parsed.maxOutputTokens,
+					maxResponseBytes: args.args.budget.maxResponseBytes,
+					signal: controller.signal
+				}),
+				receipt: (result) => result.receipt,
+				receiptFromError: () => ({
+					model: args.args.model,
+					inputTokens: 0,
+					outputTokens: 0,
+					costUnknown: true,
+					usageUnknown: true
+				})
+			});
+			if (!paid.succeeded) {
+				chargedForBudget = paid.receipt ? paid.receipt.usageUnknown || paid.receipt.costUnknown ? maximumCostUsd : paid.receipt.costUsd : 0;
+				sendJsonIfOpen(response, isAbortError(paid.error) ? 504 : paid.error instanceof ProviderResponseTooLargeError ? 502 : 429, { error: paid.error.message });
+				return;
+			}
+			chargedForBudget = paid.value.usageComplete ? paid.receipt.costUsd : maximumCostUsd;
+			if (!paid.value.usageComplete) {
+				sendJsonIfOpen(response, 502, { error: paid.value.usageError ?? "optimizer model response omitted complete token usage" });
+				return;
+			}
+			if (paid.value.usageError) {
+				sendJsonIfOpen(response, 502, { error: paid.value.usageError });
+				return;
+			}
+			if (paid.value.status >= 200 && paid.value.status < 300) args.recordSuccessfulCompletion();
+			if (response.destroyed || response.writableEnded) return;
+			response.writeHead(paid.value.status, {
+				"content-type": paid.value.contentType,
+				"content-length": String(paid.value.body.byteLength)
+			});
+			response.end(paid.value.body);
+		} finally {
+			clearTimeout(timeout);
+			args.settleReservation(maximumCostUsd, chargedForBudget);
+		}
+	} catch (error) {
+		sendJsonIfOpen(response, error instanceof RequestBodyTooLargeError ? 413 : error instanceof Error && isAbortError(error) ? 503 : 400, { error: toErrorMessage(error) });
+	}
+}
+async function waitForActiveHandlers(activeHandlers) {
+	while (activeHandlers.size > 0) await Promise.allSettled([...activeHandlers]);
+}
+function sendJsonIfOpen(response, status, body) {
+	if (response.destroyed || response.writableEnded) return;
+	sendJson(response, status, body);
+}
+async function forwardModelProxyRequest(args) {
+	const upstream = modelProxyUpstreamUrl(args.upstreamBaseUrl, args.path);
+	const response = await args.fetchImpl(upstream, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${args.upstreamApiKey}`,
+			"content-type": "application/json"
+		},
+		body: args.body.buffer.slice(args.body.byteOffset, args.body.byteOffset + args.body.byteLength),
+		signal: args.signal,
+		redirect: "error"
+	});
+	const body = await readProviderResponseBody(response, args.maxResponseBytes);
+	const usage = parseProviderUsage(body);
+	const successful = response.status >= 200 && response.status < 300;
+	const zeroUsage = successful && usage !== void 0 && usage.inputTokens + usage.outputTokens + (usage.cachedTokens ?? 0) + (usage.cacheWriteTokens ?? 0) === 0;
+	const usageError = zeroUsage ? "optimizer model provider reported zero token usage for a successful response" : successful && usage !== void 0 && usage.outputTokens > args.maxOutputTokens ? `optimizer model provider reported ${usage.outputTokens} output tokens, exceeding requested limit ${args.maxOutputTokens}` : void 0;
+	return {
+		status: response.status,
+		contentType: response.headers.get("content-type") ?? "application/json",
+		body,
+		receipt: usage && !zeroUsage ? {
+			model: args.model,
+			...usage,
+			...usage.actualCostUsd === void 0 ? { customTokenPricing: args.pricing } : {}
+		} : {
+			model: args.model,
+			inputTokens: 0,
+			outputTokens: 0,
+			costUnknown: true,
+			usageUnknown: true
+		},
+		usageComplete: usage !== void 0 && !zeroUsage,
+		...usageError ? { usageError } : {}
+	};
+}
+function parseModelProxyRequest(body, expectedModel, budget) {
+	let value;
+	try {
+		value = JSON.parse(Buffer.from(body).toString("utf8"));
+	} catch {
+		throw new Error("optimizer model request must be valid JSON");
+	}
+	if (!isRecord(value)) throw new Error("optimizer model request must be a JSON object");
+	if (value.model !== expectedModel) throw new Error(`optimizer model request must use configured model '${expectedModel}'`);
+	if (value.stream !== void 0 && value.stream !== false) throw new Error("streaming optimizer model requests are not supported");
+	for (const field of [
+		"n",
+		"best_of",
+		"candidate_count",
+		"num_candidates"
+	]) if (value[field] !== void 0 && value[field] !== 1) throw new Error(`optimizer model request ${field} must be 1 when supplied`);
+	const suppliedMaximums = [
+		value.max_output_tokens,
+		value.max_completion_tokens,
+		value.max_tokens
+	].filter((maximum) => maximum !== void 0);
+	if (suppliedMaximums.length === 0 || suppliedMaximums.some((maximum) => !Number.isSafeInteger(maximum) || maximum <= 0)) throw new Error("optimizer model request requires a positive output-token limit");
+	const maxOutputTokens = Math.max(...suppliedMaximums);
+	if (maxOutputTokens > budget.maxOutputTokensPerRequest) throw new Error("optimizer model request exceeds maxOutputTokensPerRequest");
+	return { maxOutputTokens };
+}
+function modelProxyUpstreamUrl(baseUrl, requestPath) {
+	const upstream = new URL(baseUrl);
+	const basePath = upstream.pathname.replace(/\/+$/, "");
+	upstream.pathname = `${basePath}${basePath.endsWith("/v1") ? requestPath.replace(/^\/v1/, "") : requestPath}`;
+	return upstream.toString();
+}
+function parseProviderUsage(body) {
+	let value;
+	try {
+		value = JSON.parse(Buffer.from(body).toString("utf8"));
+	} catch {
+		return;
+	}
+	if (!isRecord(value) || !isRecord(value.usage)) return void 0;
+	const usage = value.usage;
+	const totalInputTokens = usage.input_tokens ?? usage.prompt_tokens;
+	const outputTokens = usage.output_tokens ?? usage.completion_tokens;
+	if (!Number.isSafeInteger(totalInputTokens) || totalInputTokens < 0 || !Number.isSafeInteger(outputTokens) || outputTokens < 0) return;
+	const inputDetails = isRecord(usage.input_tokens_details) ? usage.input_tokens_details : isRecord(usage.prompt_tokens_details) ? usage.prompt_tokens_details : {};
+	const outputDetails = isRecord(usage.output_tokens_details) ? usage.output_tokens_details : isRecord(usage.completion_tokens_details) ? usage.completion_tokens_details : {};
+	const cachedTokens = optionalTokenCount(inputDetails, [
+		"cached_tokens",
+		"cache_read_tokens",
+		"cache_read_input_tokens"
+	]);
+	const cacheWriteTokens = optionalTokenCount(inputDetails, [
+		"cache_write_tokens",
+		"cache_creation_tokens",
+		"cache_creation_input_tokens"
+	]);
+	const reasoningTokens = optionalTokenCount(outputDetails, ["reasoning_tokens"]);
+	const actualCostUsd = typeof usage.cost === "number" && Number.isFinite(usage.cost) && usage.cost >= 0 ? usage.cost : void 0;
+	if (cachedTokens === INVALID_TOKEN_COUNT || cacheWriteTokens === INVALID_TOKEN_COUNT || reasoningTokens === INVALID_TOKEN_COUNT) return;
+	const classifiedInputTokens = (cachedTokens ?? 0) + (cacheWriteTokens ?? 0);
+	if (classifiedInputTokens > totalInputTokens || (reasoningTokens ?? 0) > outputTokens) return;
+	return {
+		inputTokens: totalInputTokens - classifiedInputTokens,
+		outputTokens,
+		...cachedTokens === void 0 ? {} : { cachedTokens },
+		...cacheWriteTokens === void 0 ? {} : { cacheWriteTokens },
+		...reasoningTokens === void 0 ? {} : { reasoningTokens },
+		...actualCostUsd === void 0 ? {} : { actualCostUsd }
+	};
+}
+const INVALID_TOKEN_COUNT = Symbol("invalid-token-count");
+function optionalTokenCount(details, fields) {
+	let found;
+	for (const field of fields) {
+		const value = details[field];
+		if (value === void 0 || value === null) continue;
+		if (!Number.isSafeInteger(value) || value < 0) return INVALID_TOKEN_COUNT;
+		if (found !== void 0 && found !== value) return INVALID_TOKEN_COUNT;
+		found = value;
+	}
+	return found;
+}
+function conservativeMaximumUsage(inputTokenUpperBound, outputTokenUpperBound, pricing) {
+	const inputRates = [
+		pricing.inputUsdPerMillion,
+		pricing.cachedInputUsdPerMillion ?? pricing.inputUsdPerMillion,
+		pricing.cacheWriteUsdPerMillion ?? pricing.inputUsdPerMillion
+	];
+	const mostExpensiveInputClass = inputRates.indexOf(Math.max(...inputRates));
+	return {
+		inputTokens: mostExpensiveInputClass === 0 ? inputTokenUpperBound : 0,
+		...mostExpensiveInputClass === 1 ? { cachedTokens: inputTokenUpperBound } : {},
+		...mostExpensiveInputClass === 2 ? { cacheWriteTokens: inputTokenUpperBound } : {},
+		outputTokens: outputTokenUpperBound
+	};
+}
+async function readProviderResponseBody(response, maxBytes) {
+	const declaredLength = response.headers.get("content-length");
+	if (declaredLength !== null) {
+		const parsedLength = Number(declaredLength);
+		if (Number.isFinite(parsedLength) && parsedLength > maxBytes) throw new ProviderResponseTooLargeError();
+	}
+	if (!response.body) return /* @__PURE__ */ new Uint8Array();
+	const reader = response.body.getReader();
+	const chunks = [];
+	let totalBytes = 0;
+	try {
+		while (true) {
+			const next = await reader.read();
+			if (next.done) break;
+			totalBytes += next.value.byteLength;
+			if (totalBytes > maxBytes) {
+				await reader.cancel();
+				throw new ProviderResponseTooLargeError();
+			}
+			chunks.push(next.value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const body = new Uint8Array(totalBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return body;
+}
+function assertModelProxyConfig(args) {
+	for (const [label, value] of [
+		["upstreamBaseUrl", args.upstreamBaseUrl],
+		["upstreamApiKey", args.upstreamApiKey],
+		["model", args.model],
+		["phase", args.phase],
+		["actor", args.actor]
+	]) if (typeof value !== "string" || !value.trim() || value.trim() !== value) throw new Error(`external optimizer model proxy: ${label} must be trimmed and non-empty`);
+	let parsed;
+	try {
+		parsed = new URL(args.upstreamBaseUrl);
+	} catch {
+		throw new Error("external optimizer model proxy: upstreamBaseUrl must be an HTTP(S) URL");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.search || parsed.hash) throw new Error("external optimizer model proxy: upstreamBaseUrl must be an HTTP(S) URL without credentials, query, or fragment");
+	assertExternalOptimizerModelBudget(args.budget, "external optimizer model proxy: budget");
+	if (args.tags !== void 0) {
+		for (const [key, value] of Object.entries(args.tags)) if (!key.trim() || key.trim() !== key || !value.trim() || value.trim() !== value) throw new Error("external optimizer model proxy: tags must be trimmed and non-empty");
+	}
+	if (args.initialUsage !== void 0) {
+		if (!Number.isSafeInteger(args.initialUsage.requests) || args.initialUsage.requests < 0 || !Number.isFinite(args.initialUsage.costUsd) || args.initialUsage.costUsd < 0) throw new Error("external optimizer model proxy: initialUsage must contain non-negative requests and cost");
+		if (args.initialUsage.requests > args.budget.maxRequests || args.initialUsage.costUsd > args.budget.maxCostUsd + Number.EPSILON) throw new Error("external optimizer model proxy: initialUsage exceeds the configured budget");
+	}
+}
+var RequestBodyTooLargeError = class extends Error {};
+var ProviderResponseTooLargeError = class extends Error {
+	constructor() {
+		super("optimizer model response exceeds maxResponseBytes");
+	}
+};
+function readBody(request, maximumBytes) {
+	return new Promise((resolvePromise, reject) => {
+		let size = 0;
+		let tooLarge = false;
+		const chunks = [];
+		request.on("data", (chunk) => {
+			if (tooLarge) return;
+			size += chunk.byteLength;
+			if (size > maximumBytes) {
+				tooLarge = true;
+				chunks.length = 0;
+				return;
+			}
+			chunks.push(chunk);
+		});
+		request.on("error", reject);
+		request.on("end", () => {
+			if (tooLarge) {
+				reject(new RequestBodyTooLargeError("optimizer model request body too large"));
+				return;
+			}
+			resolvePromise(new Uint8Array(Buffer.concat(chunks)));
+		});
+	});
+}
+function randomLocalToken() {
+	return randomBytes(32).toString("hex");
+}
+function isAbortError(error) {
+	return error.name === "AbortError" || error.message.toLowerCase().includes("abort");
+}
+function toErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/campaign/external-optimizer-resources.ts
+async function runWithCleanup(args) {
+	let value;
+	let operationError;
+	try {
+		value = await args.run();
+	} catch (cause) {
+		operationError = toError(cause);
+	}
+	let cleanupError;
+	try {
+		await args.cleanup();
+	} catch (cause) {
+		cleanupError = toError(cause);
+	}
+	if (operationError && cleanupError) throw new AggregateError([operationError, cleanupError], `${operationError.message}; ${args.label} cleanup failed: ${cleanupError.message}`);
+	if (operationError) throw operationError;
+	if (cleanupError) throw new Error(`${args.label} cleanup failed: ${cleanupError.message}`, { cause: cleanupError });
+	return value;
+}
+async function closeExternalOptimizerResources(args) {
+	const errors = (await Promise.allSettled([...args.modelProxy ? [args.modelProxy.close()] : [], args.callback.close()])).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+	if (errors.length > 0) throw new AggregateError(errors, `${args.label}: failed to close optimizer resources`);
+}
+function toError(cause) {
+	return cause instanceof Error ? cause : new Error(String(cause));
+}
+//#endregion
+//#region src/campaign/external-optimizer-subprocess.ts
+const MAX_PROCESS_OUTPUT_CHARS = 64e3;
+const MAX_PROCESS_INPUT_BYTES = 64 * 1024 * 1024;
+const MAX_PROCESS_RESULT_BYTES = 4 * 1024 * 1024;
+const PROCESS_TERMINATION_GRACE_MS = 5e3;
+const PROCESS_TERMINATION_POLL_MS = 25;
+const PROCESS_KILL_WAIT_MS = 1e3;
+const MAX_TIMER_DELAY_MS = 2147483647;
+const PROCESS_OUTPUT_HEAD_CHARS = MAX_PROCESS_OUTPUT_CHARS / 2;
+async function runExternalOptimizerProcess(args) {
+	if (!Number.isSafeInteger(args.timeoutMs) || args.timeoutMs <= 0 || args.timeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`${args.label} timeoutMs must be between 1 and ${MAX_TIMER_DELAY_MS}`);
+	if (process.platform === "win32") throw new Error(`${args.label} requires POSIX process-group cleanup; run the optimizer through WSL or Linux`);
+	throwIfAborted(args.signal, args.label);
+	const dir = await mkdtemp(join(tmpdir(), args.tempPrefix));
+	const inputPath = join(dir, "input.json");
+	const outputPath = join(dir, "output.json");
+	return runWithCleanup({
+		label: `${args.label} temporary directory`,
+		run: async () => {
+			const serializedInput = JSON.stringify(args.input);
+			if (serializedInput === void 0) throw new Error(`${args.label} input must be JSON-serializable`);
+			const inputJson = `${serializedInput}\n`;
+			const inputBytes = Buffer.byteLength(inputJson);
+			if (inputBytes > MAX_PROCESS_INPUT_BYTES) throw new Error(`${args.label} input exceeds ${MAX_PROCESS_INPUT_BYTES} bytes (${inputBytes})`);
+			await writeFile(inputPath, inputJson);
+			const command = resolveRunnerCommand(args.runner?.command ?? "python");
+			const commandArgs = [
+				...args.runner?.args ?? ["-m", args.module],
+				"--input",
+				inputPath,
+				"--output",
+				outputPath
+			];
+			await runProcess({
+				label: args.label,
+				command,
+				args: commandArgs,
+				cwd: dir,
+				env: args.runner?.env,
+				timeoutMs: args.timeoutMs,
+				signal: args.signal
+			});
+			throwIfAborted(args.signal, args.label);
+			const raw = JSON.parse(await readBoundedTextFile(outputPath, MAX_PROCESS_RESULT_BYTES, `${args.label} output`));
+			throwIfAborted(args.signal, args.label);
+			if (!isRecord(raw)) throw new Error(`${args.label} output must be a JSON object`);
+			return raw;
+		},
+		cleanup: () => rm(dir, {
+			recursive: true,
+			force: true
+		})
+	});
+}
+function resolveRunnerCommand(command) {
+	if (isAbsolute(command) || !command.includes("/") && !command.includes("\\")) return command;
+	return resolve(command);
+}
+async function readBoundedTextFile(path, maxBytes, label) {
+	if (!(await lstat(path)).isFile()) throw new Error(`${label} must be a regular file`);
+	const file = await open(path, "r");
+	try {
+		const buffer = Buffer.allocUnsafe(maxBytes + 1);
+		let bytesRead = 0;
+		while (bytesRead < buffer.byteLength) {
+			const chunk = await file.read(buffer, bytesRead, buffer.byteLength - bytesRead, bytesRead);
+			if (chunk.bytesRead === 0) break;
+			bytesRead += chunk.bytesRead;
+		}
+		if (bytesRead > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes`);
+		return buffer.subarray(0, bytesRead).toString("utf8");
+	} finally {
+		await file.close();
+	}
+}
+function runProcess(args) {
+	throwIfAborted(args.signal, args.label);
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(args.command, args.args, {
+			cwd: args.cwd,
+			env: {
+				...safeProcessEnvironment(),
+				...args.env
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			detached: process.platform !== "win32",
+			windowsHide: true
+		});
+		const stdout = createProcessOutputCapture();
+		const stderr = createProcessOutputCapture();
+		let settled = false;
+		let timeout;
+		const onAbort = () => finish(abortReason(args.signal, args.label));
+		const finish = (error) => {
+			if (settled) return;
+			settled = true;
+			if (timeout) clearTimeout(timeout);
+			args.signal?.removeEventListener("abort", onAbort);
+			terminateProcessTree(child).then(() => {
+				if (error) reject(error);
+				else resolvePromise();
+			}, (cleanupError) => {
+				if (error) {
+					const cleanup = cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError));
+					reject(new AggregateError([error, cleanup], `${error.message}; ${args.label} process cleanup failed: ${cleanup.message}`));
+					return;
+				}
+				reject(/* @__PURE__ */ new Error(`${args.label} process cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`));
+			});
+		};
+		timeout = setTimeout(() => {
+			finish(/* @__PURE__ */ new Error(`${args.label} exceeded ${args.timeoutMs}ms`));
+		}, args.timeoutMs);
+		args.signal?.addEventListener("abort", onAbort, { once: true });
+		if (args.signal?.aborted) onAbort();
+		child.stdout.on("data", (chunk) => {
+			appendProcessOutput(stdout, chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			appendProcessOutput(stderr, chunk);
+		});
+		child.on("error", (error) => {
+			finish(/* @__PURE__ */ new Error(`${args.label} could not start: ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				finish();
+				return;
+			}
+			finish(/* @__PURE__ */ new Error(`${args.label} exited ${String(code)}. stderr=${summarizeProcessOutput(stderr)} stdout=${summarizeProcessOutput(stdout)}`));
+		});
+	});
+}
+function throwIfAborted(signal, label) {
+	if (signal?.aborted) throw abortReason(signal, label);
+}
+function abortReason(signal, label) {
+	return signal.reason instanceof Error ? signal.reason : new Error(`${label} aborted`, { cause: signal.reason });
+}
+function safeProcessEnvironment() {
+	return Object.fromEntries([
+		"PATH",
+		"HOME",
+		"USER",
+		"LOGNAME",
+		"SHELL",
+		"TMPDIR",
+		"TMP",
+		"TEMP",
+		"LANG",
+		"LANGUAGE",
+		"LC_ALL",
+		"VIRTUAL_ENV",
+		"PYTHONPATH",
+		"SYSTEMROOT",
+		"COMSPEC",
+		"PATHEXT",
+		"WINDIR"
+	].flatMap((name) => {
+		const value = process.env[name];
+		return value === void 0 ? [] : [[name, value]];
+	}));
+}
+async function terminateProcessTree(child) {
+	const pid = child.pid;
+	if (!pid) return;
+	if (process.platform === "win32") throw new Error("native Windows process-tree cleanup is unsupported");
+	if (!signalProcessGroup(pid, "SIGTERM")) return;
+	if (await waitForProcessGroupExit(pid, PROCESS_TERMINATION_GRACE_MS)) return;
+	if (!signalProcessGroup(pid, "SIGKILL")) return;
+	if (await waitForProcessGroupExit(pid, PROCESS_KILL_WAIT_MS)) return;
+	throw new Error(`process group ${pid} remained alive after SIGKILL`);
+}
+function signalProcessGroup(pid, signal) {
+	try {
+		process.kill(-pid, signal);
+		return true;
+	} catch (error) {
+		if (isMissingProcessError(error)) return false;
+		throw error;
+	}
+}
+async function waitForProcessGroupExit(pid, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (processGroupExists(pid)) {
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) return false;
+		await new Promise((resolve) => setTimeout(resolve, Math.min(PROCESS_TERMINATION_POLL_MS, remainingMs)));
+	}
+	return true;
+}
+function processGroupExists(pid) {
+	try {
+		process.kill(-pid, 0);
+		return true;
+	} catch (error) {
+		if (isMissingProcessError(error)) return false;
+		throw error;
+	}
+}
+function isMissingProcessError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ESRCH";
+}
+function createProcessOutputCapture() {
+	return {
+		full: "",
+		head: "",
+		tail: "",
+		totalChars: 0
+	};
+}
+function appendProcessOutput(capture, chunk) {
+	const text = chunk.toString();
+	capture.totalChars += text.length;
+	if (capture.full !== void 0) {
+		const combined = `${capture.full}${text}`;
+		if (combined.length <= MAX_PROCESS_OUTPUT_CHARS) {
+			capture.full = combined;
+			return;
+		}
+		capture.head = combined.slice(0, PROCESS_OUTPUT_HEAD_CHARS);
+		capture.tail = combined.slice(-32e3);
+		capture.full = void 0;
+		return;
+	}
+	capture.tail = `${capture.tail}${text}`.slice(-32e3);
+}
+function summarizeProcessOutput(capture, max = 4e3) {
+	const compact = (capture.full ?? `${capture.head}\n...[${capture.totalChars - capture.head.length - capture.tail.length} chars omitted]...\n${capture.tail}`).trim().replace(/\s+/g, " ");
+	if (compact.length <= max) return compact;
+	const headChars = Math.floor(max / 3);
+	const tailChars = max - headChars;
+	return `${compact.slice(0, headChars)}...[${compact.length - max} chars omitted]...${compact.slice(-tailChars)}`;
+}
+//#endregion
+//#region src/campaign/search-ledger-errors.ts
+/** Base error for invalid search-ledger input or operations. */
+var SearchLedgerError = class extends ValidationError {};
+/** Error raised when durable search-ledger data fails an integrity check. */
+var SearchLedgerIntegrityError = class extends SearchLedgerError {};
+/** Error raised when an event identifier is reused with different content. */
+var SearchLedgerConflictError = class extends SearchLedgerError {};
+//#endregion
+//#region src/campaign/search-ledger-file.ts
+/** Campaign binding of the generic journal file layer to search-ledger errors. */
+const SEARCH_LEDGER_FILE_CONTEXT = {
+	subject: "search ledger",
+	integrityError: (message, options) => new SearchLedgerIntegrityError(message, options)
+};
+function appendSearchLedgerLine(path, line) {
+	appendLedgerLine(path, line, SEARCH_LEDGER_FILE_CONTEXT);
+}
+function tryWithSearchLedgerFileLock(ledgerPath, run) {
+	return tryWithLedgerFileLock(ledgerPath, SEARCH_LEDGER_FILE_CONTEXT, run);
+}
+//#endregion
+//#region src/campaign/storage.ts
+/** Node-filesystem storage — the default. Lazily requires `node:fs` so the
+*  module imports cleanly in non-Node runtimes (where the caller passes
+*  `inMemoryCampaignStorage` instead and never constructs this).
+*
+*  `createRequire(import.meta.url)` is the ESM-native lazy require — a bare
+*  `require` is a ReferenceError under `"type": "module"`, which is exactly
+*  the shape this package publishes. */
+function fsCampaignStorage() {
+	const { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } = createRequire(import.meta.url)("node:fs");
+	return {
+		ensureDir(dir) {
+			if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		},
+		exists(path) {
+			return existsSync(path);
+		},
+		read(path) {
+			try {
+				return readFileSync(path, "utf8");
+			} catch {
+				return;
+			}
+		},
+		write(path, content) {
+			writeFileSync(path, content);
+		},
+		append(path, content, expectedBytes) {
+			const result = tryWithSearchLedgerFileLock(path, () => {
+				let actualBytes = 0;
+				try {
+					actualBytes = statSync(path).size;
+				} catch (error) {
+					if (error.code !== "ENOENT") throw error;
+				}
+				if (actualBytes !== expectedBytes) return void 0;
+				appendSearchLedgerLine(path, content);
+				return expectedBytes + Buffer.byteLength(content);
+			});
+			return result.acquired ? result.value : void 0;
+		}
+	};
+}
+/** In-memory storage for filesystem-less runtimes. Artifacts + trace spans
+*  live in a `Map` for the duration of the run; the `CampaignResult` is
+*  fully populated, but nothing is persisted to disk. */
+function inMemoryCampaignStorage() {
+	const files = /* @__PURE__ */ new Map();
+	const dirs = /* @__PURE__ */ new Set();
+	return {
+		ensureDir(dir) {
+			dirs.add(dir);
+		},
+		exists(path) {
+			return files.has(path) || dirs.has(path);
+		},
+		read(path) {
+			const value = files.get(path);
+			if (value === void 0) return void 0;
+			return typeof value === "string" ? value : new TextDecoder().decode(value);
+		},
+		write(path, content) {
+			files.set(path, content);
+		},
+		append(path, content, expectedBytes) {
+			const current = files.get(path);
+			const currentText = current === void 0 ? "" : typeof current === "string" ? current : new TextDecoder().decode(current);
+			const currentBytes = new TextEncoder().encode(currentText).byteLength;
+			if (currentBytes !== expectedBytes) return void 0;
+			files.set(path, `${currentText}${content}`);
+			return currentBytes + new TextEncoder().encode(content).byteLength;
+		}
+	};
+}
+/** Open the durable spend account stored beside a logical run. */
+function createRunCostLedger(input) {
+	const path = join(input.runDir, "cost-ledger.jsonl");
+	input.storage.ensureDir(input.runDir);
+	return new CostLedger({
+		costCeilingUsd: input.costCeilingUsd,
+		persistence: {
+			read: () => {
+				const stored = input.storage.read(path);
+				if (stored === void 0 && input.storage.exists(path)) throw new Error(`CostLedger: cannot read existing event log '${path}'`);
+				const events = stored ?? "";
+				return {
+					revision: String(new TextEncoder().encode(events).byteLength),
+					events
+				};
+			},
+			append: (expectedRevision, event) => {
+				const expectedBytes = Number(expectedRevision);
+				if (!Number.isSafeInteger(expectedBytes) || expectedBytes < 0) throw new Error(`CostLedger: invalid storage revision '${expectedRevision}'`);
+				const next = input.storage.append(path, event, expectedBytes);
+				return next === void 0 ? void 0 : String(next);
+			}
+		}
+	});
+}
+//#endregion
+//#region src/campaign/single-run-lock.ts
+/**
+* Single-run lock for evaluations that share one mutable environment.
+*
+* Two concurrent runs against a shared stateful gym silently corrupt each
+* other: each resets/mutates environment state mid-cell of the other, and
+* every score from both becomes garbage that LOOKS like worker variance
+* (agent-lab R357 burned hours on flip-flopping scores before tracing them
+* to exactly this). The fix is a pid lockfile: refuse to start while a live
+* holder exists, reclaim stale locks whose pid is gone, release only if the
+* lock is still ours.
+*
+* `alsoCheck` exists because independent runners can guard the same shared
+* resource with differently named lockfiles; a runner must respect all of
+* them even though it writes only its own.
+*/
+function assertAvailable(path) {
+	const unavailable = probeAtomicFileLock({ lockPath: path });
+	if (unavailable) throw unavailableError(path, unavailable);
+}
+function unavailableError(path, unavailable) {
+	if (unavailable.reason === "recovery") return /* @__PURE__ */ new Error(`single-run lock recovery is already in progress (${path}); refusing a concurrent run`);
+	return /* @__PURE__ */ new Error(`single-run lock held by live pid ${unavailable.holder.pid} (${path}); refusing a concurrent run on the shared resource`);
+}
+/**
+* Acquire the lock or throw naming the live holder. A stale lock (holder pid
+* no longer running) is reclaimed by one contender. An interrupted reclaim
+* leaves a marker that fails closed instead of admitting overlapping runs.
+*/
+function acquireSingleRunLock(opts) {
+	const pid = opts.pid ?? process.pid;
+	if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("single-run lock pid must be a positive integer");
+	for (const path of opts.alsoCheck ?? []) assertAvailable(path);
+	const acquisition = tryAcquireAtomicFileLock({
+		lockPath: opts.lockPath,
+		pid
+	});
+	if (!acquisition.acquired) throw unavailableError(opts.lockPath, acquisition);
+	const releaseOnExit = opts.releaseOnExit ?? true;
+	let released = false;
+	const release = () => {
+		if (released) return;
+		released = true;
+		if (releaseOnExit) process.off("exit", release);
+		try {
+			acquisition.lock.release();
+		} catch {}
+	};
+	try {
+		for (const path of opts.alsoCheck ?? []) assertAvailable(path);
+	} catch (error) {
+		release();
+		throw error;
+	}
+	if (releaseOnExit) process.on("exit", release);
+	return { release };
+}
+//#endregion
+export { safePathComponent as C, removeCredentialEnvironment as S, assertJsonValue as _, SEARCH_LEDGER_FILE_CONTEXT as a, isExternalTextCandidate as b, SearchLedgerIntegrityError as c, runWithCleanup as d, startExternalOptimizerModelProxy as f, assertExternalOptimizerModelBudget as g, sendJson as h, inMemoryCampaignStorage as i, runExternalOptimizerProcess as l, listenLocal as m, createRunCostLedger as n, SearchLedgerConflictError as o, closeServer as p, fsCampaignStorage as r, SearchLedgerError as s, acquireSingleRunLock as t, closeExternalOptimizerResources as u, assertNoCredentialValues as v, isRecord as x, isCandidateText as y };
+
+//# sourceMappingURL=single-run-lock-BTTtPZ9N.js.map