@jshookmcp/jshook 0.2.8 → 0.3.0

package/dist/artifactRetention-CPXkUJXp.mjs

@@ -0,0 +1,598 @@
+import { t as logger } from "./logger-Dh_xb7_2.mjs";
+import { b as CACHE_LOW_HIT_RATE_THRESHOLD, hr as TOKEN_BUDGET_MAX_TOKENS, y as CACHE_GLOBAL_MAX_SIZE_BYTES } from "./constants-CDZLOoVv.mjs";
+import { c as getConfig, i as getProjectRoot, n as getDebuggerSessionsDir } from "./outputPaths-um7lCRY3.mjs";
+import { n as getArtifactDir, r as getArtifactsRoot } from "./artifacts-DkfosXH3.mjs";
+import { join, resolve } from "node:path";
+import { readdir, rm, stat } from "node:fs/promises";
+//#region src/utils/TokenBudgetManager.ts
+var TokenBudgetManager = class TokenBudgetManager {
+	static instance;
+	MAX_TOKENS = TOKEN_BUDGET_MAX_TOKENS;
+	WARNING_THRESHOLDS = [
+		.8,
+		.9,
+		.95
+	];
+	BYTES_PER_TOKEN = 4;
+	AUTO_CLEANUP_THRESHOLD = .9;
+	HISTORY_RETENTION = 300 * 1e3;
+	currentUsage = 0;
+	toolCallHistory = [];
+	warnings = /* @__PURE__ */ new Set();
+	sessionStartTime = Date.now();
+	trackingEnabled = true;
+	MAX_ESTIMATION_DEPTH = 4;
+	MAX_ESTIMATION_ARRAY_ITEMS = 50;
+	MAX_ESTIMATION_OBJECT_KEYS = 50;
+	MAX_ESTIMATION_STRING_LENGTH = 2e3;
+	MAX_ESTIMATION_BYTES = 256 * 1024;
+	externalCleanupFn = null;
+	constructor() {
+		logger.info("TokenBudgetManager initialized");
+	}
+	/** @deprecated Use constructor injection. Kept for backward compatibility. */
+	static getInstance() {
+		if (!this.instance) this.instance = new TokenBudgetManager();
+		return this.instance;
+	}
+	/**
+	* Register a callback invoked during auto-cleanup to clear external caches.
+	* This replaces the previous hard dependency on DetailedDataManager.getInstance().
+	*/
+	setExternalCleanup(fn) {
+		this.externalCleanupFn = fn;
+	}
+	recordToolCall(toolName, request, response) {
+		if (!this.trackingEnabled) return;
+		try {
+			const requestSize = this.calculateSize(request);
+			const responseSize = this.calculateSize(response);
+			const totalSize = requestSize + responseSize;
+			const estimatedTokens = this.estimateTokens(totalSize);
+			this.currentUsage += estimatedTokens;
+			const record = {
+				toolName,
+				timestamp: Date.now(),
+				requestSize,
+				responseSize,
+				estimatedTokens,
+				cumulativeTokens: this.currentUsage
+			};
+			this.toolCallHistory.push(record);
+			logger.debug(`Token usage: ${this.currentUsage}/${this.MAX_TOKENS} (${this.getUsagePercentage()}%) | Tool: ${toolName} | Size: ${(totalSize / 1024).toFixed(1)}KB | Tokens: ${estimatedTokens}`);
+			this.checkWarnings();
+			if (this.shouldAutoCleanup()) this.autoCleanup();
+		} catch (error) {
+			logger.error("Failed to record tool call:", error);
+		}
+	}
+	isRecord(value) {
+		return value !== null && typeof value === "object";
+	}
+	hasDetailedSummarySize(value) {
+		if (!this.isRecord(value) || !("detailId" in value)) return false;
+		const summary = value.summary;
+		if (!this.isRecord(summary)) return false;
+		const { size } = summary;
+		return typeof size === "number" && Number.isFinite(size) && size > 0;
+	}
+	/**
+	* Fast path for common MCP tool response envelopes:
+	*   { content: [{ type: 'text', text: string }], isError?: boolean }
+	*
+	* Avoids full recursive normalization by estimating size directly from
+	* the text payload with the same truncation semantics.
+	*/
+	tryEstimateMcpEnvelope(data) {
+		if (!this.isRecord(data)) return null;
+		const content = data["content"];
+		if (!Array.isArray(content) || content.length === 0) return null;
+		const first = content[0];
+		if (!this.isRecord(first)) return null;
+		if (first["type"] !== "text" || typeof first["text"] !== "string") return null;
+		const text = first["text"];
+		const truncated = text.length > this.MAX_ESTIMATION_STRING_LENGTH ? `${text.slice(0, this.MAX_ESTIMATION_STRING_LENGTH)}...[truncated:${text.length}]` : text;
+		const overhead = 42 + (data["isError"] === true ? 14 : 0);
+		const textBytes = Buffer.byteLength(truncated, "utf8");
+		return Math.min(overhead + textBytes, this.MAX_ESTIMATION_BYTES);
+	}
+	calculateSize(data) {
+		try {
+			if (this.hasDetailedSummarySize(data)) return Math.min(data.summary.size, this.MAX_ESTIMATION_BYTES);
+			const mcpSize = this.tryEstimateMcpEnvelope(data);
+			if (mcpSize !== null) return mcpSize;
+			const normalized = this.normalizeForSizeEstimate(data, 0, /* @__PURE__ */ new WeakSet());
+			const serialized = JSON.stringify(normalized);
+			if (!serialized) return 0;
+			return Math.min(Buffer.byteLength(serialized, "utf8"), this.MAX_ESTIMATION_BYTES);
+		} catch (error) {
+			logger.warn("Failed to calculate data size:", error);
+			return 0;
+		}
+	}
+	normalizeForSizeEstimate(value, depth, seen) {
+		if (value === null || value === void 0) return value;
+		const valueType = typeof value;
+		if (valueType === "boolean" || valueType === "number") return value;
+		if (valueType === "string") {
+			const stringValue = value;
+			if (stringValue.length <= this.MAX_ESTIMATION_STRING_LENGTH) return stringValue;
+			const marker = `...[truncated:${stringValue.length}]`;
+			const maxPrefixLength = Math.max(this.MAX_ESTIMATION_STRING_LENGTH - marker.length, 0);
+			return `${stringValue.slice(0, maxPrefixLength)}${marker}`;
+		}
+		if (valueType === "bigint") return value.toString();
+		if (valueType === "symbol") return value.toString();
+		if (valueType === "function") return "[Function]";
+		if (value instanceof Error) return {
+			name: value.name,
+			message: value.message,
+			stack: value.stack?.slice(0, this.MAX_ESTIMATION_STRING_LENGTH)
+		};
+		if (Buffer.isBuffer(value)) return `[Buffer:${value.byteLength}]`;
+		if (depth >= this.MAX_ESTIMATION_DEPTH) {
+			if (Array.isArray(value)) return `[Array:${value.length}]`;
+			return "[Object]";
+		}
+		if (Array.isArray(value)) {
+			const limited = value.slice(0, this.MAX_ESTIMATION_ARRAY_ITEMS).map((item) => this.normalizeForSizeEstimate(item, depth + 1, seen));
+			if (value.length > this.MAX_ESTIMATION_ARRAY_ITEMS) limited.push(`[truncated:${value.length - this.MAX_ESTIMATION_ARRAY_ITEMS}]`);
+			return limited;
+		}
+		if (valueType === "object") {
+			/* v8 ignore next 3 */
+			if (!this.isRecord(value)) return "[Object]";
+			if (seen.has(value)) return "[Circular]";
+			seen.add(value);
+			const entries = Object.entries(value);
+			const limitedEntries = entries.slice(0, this.MAX_ESTIMATION_OBJECT_KEYS);
+			const out = {};
+			for (const [key, nestedValue] of limitedEntries) out[key] = this.normalizeForSizeEstimate(nestedValue, depth + 1, seen);
+			if (entries.length > this.MAX_ESTIMATION_OBJECT_KEYS) out.__truncatedKeys = entries.length - this.MAX_ESTIMATION_OBJECT_KEYS;
+			return out;
+		}
+		/* v8 ignore next */
+		return String(value);
+	}
+	estimateTokens(bytes) {
+		return Math.ceil(bytes / this.BYTES_PER_TOKEN);
+	}
+	getUsagePercentage() {
+		return Math.round(this.currentUsage / this.MAX_TOKENS * 100);
+	}
+	checkWarnings() {
+		const ratio = this.currentUsage / this.MAX_TOKENS;
+		for (const threshold of this.WARNING_THRESHOLDS) if (ratio >= threshold && !this.warnings.has(threshold)) {
+			this.emitWarning(threshold);
+			this.warnings.add(threshold);
+		}
+	}
+	emitWarning(threshold) {
+		const percentage = Math.round(threshold * 100);
+		const remaining = this.MAX_TOKENS - this.currentUsage;
+		logger.warn(`Token Budget Warning: ${percentage}% used! (${this.currentUsage}/${this.MAX_TOKENS}, ${remaining} tokens remaining)`);
+		if (threshold >= .95) logger.warn("CRITICAL: Consider clearing caches or starting a new session.");
+		else if (threshold >= .9) logger.warn("HIGH: Auto-cleanup will trigger soon. Consider using summary modes.");
+		else if (threshold >= .8) logger.warn("MODERATE: Monitor usage. Use get_token_budget_stats for details.");
+	}
+	shouldAutoCleanup() {
+		return this.currentUsage / this.MAX_TOKENS >= this.AUTO_CLEANUP_THRESHOLD;
+	}
+	autoCleanup() {
+		logger.info("Auto-cleanup triggered at 90% usage.");
+		const beforeUsage = this.currentUsage;
+		if (this.externalCleanupFn) try {
+			this.externalCleanupFn();
+			logger.info("External cleanup callback invoked");
+		} catch (e) {
+			logger.warn("External cleanup callback failed:", e);
+		}
+		const cutoff = Date.now() - this.HISTORY_RETENTION;
+		const beforeCount = this.toolCallHistory.length;
+		this.toolCallHistory = this.toolCallHistory.filter((call) => call.timestamp > cutoff);
+		const removedCount = beforeCount - this.toolCallHistory.length;
+		logger.info(`Removed ${removedCount} old tool call records`);
+		this.recalculateUsage();
+		const afterUsage = this.currentUsage;
+		const freed = beforeUsage - afterUsage;
+		const freedPercentage = Math.round(freed / this.MAX_TOKENS * 100);
+		logger.info(`Cleanup complete. Freed ${freed} tokens (${freedPercentage}%). Usage: ${afterUsage}/${this.MAX_TOKENS} (${this.getUsagePercentage()}%)`);
+		const newRatio = afterUsage / this.MAX_TOKENS;
+		this.warnings = new Set(Array.from(this.warnings).filter((threshold) => newRatio >= threshold));
+	}
+	recalculateUsage() {
+		this.currentUsage = this.toolCallHistory.reduce((sum, call) => sum + call.estimatedTokens, 0);
+	}
+	getStats() {
+		const toolUsage = /* @__PURE__ */ new Map();
+		for (const call of this.toolCallHistory) {
+			const current = toolUsage.get(call.toolName) || 0;
+			toolUsage.set(call.toolName, current + call.estimatedTokens);
+		}
+		const topTools = Array.from(toolUsage.entries()).map(([tool, tokens]) => ({
+			tool,
+			tokens,
+			percentage: Math.round(tokens / this.currentUsage * 100)
+		})).toSorted((a, b) => b.tokens - a.tokens).slice(0, 10);
+		const suggestions = this.generateSuggestions(topTools);
+		const recentCalls = this.toolCallHistory.slice(-20);
+		return {
+			currentUsage: this.currentUsage,
+			maxTokens: this.MAX_TOKENS,
+			usagePercentage: this.getUsagePercentage(),
+			toolCallCount: this.toolCallHistory.length,
+			topTools,
+			warnings: Array.from(this.warnings).map((t) => Math.round(t * 100)),
+			recentCalls,
+			suggestions,
+			sessionStartTime: this.sessionStartTime
+		};
+	}
+	generateSuggestions(topTools) {
+		const suggestions = [];
+		const ratio = this.currentUsage / this.MAX_TOKENS;
+		if (ratio >= .95) suggestions.push(" CRITICAL: Clear all caches immediately or start a new session");
+		else if (ratio >= .9) suggestions.push("HIGH: Auto-cleanup triggered. Consider manual cleanup for better control");
+		else if (ratio >= .8) suggestions.push("MODERATE: Monitor usage closely. Use summary modes for large data");
+		for (const { tool, percentage } of topTools) if (percentage > 30) {
+			if (tool.includes("collect_code")) suggestions.push(` ${tool} uses ${percentage}% tokens. Try smartMode="summary" or "priority"`);
+			else if (tool.includes("get_script_source")) suggestions.push(` ${tool} uses ${percentage}% tokens. Try preview=true first`);
+			else if (tool.includes("network_get_requests")) suggestions.push(` ${tool} uses ${percentage}% tokens. Reduce limit or use filters`);
+			else if (tool.includes("page_evaluate")) suggestions.push(` ${tool} uses ${percentage}% tokens. Query specific properties instead of full objects`);
+		}
+		if (suggestions.length === 0) suggestions.push(" Token usage is healthy. Continue monitoring.");
+		return suggestions;
+	}
+	manualCleanup() {
+		logger.info("Manual cleanup requested.");
+		this.autoCleanup();
+	}
+	setTrackingEnabled(enabled) {
+		if (this.trackingEnabled === enabled) return;
+		this.trackingEnabled = enabled;
+		logger.warn(`Token budget tracking ${enabled ? "enabled" : "disabled"}`);
+	}
+	isTrackingEnabled() {
+		return this.trackingEnabled;
+	}
+	reset() {
+		logger.info("Resetting token budget...");
+		this.currentUsage = 0;
+		this.toolCallHistory = [];
+		this.warnings.clear();
+		this.sessionStartTime = Date.now();
+		logger.info("Token budget reset complete");
+	}
+};
+//#endregion
+//#region src/utils/UnifiedCacheManager.ts
+var UnifiedCacheManager = class UnifiedCacheManager {
+	static instance;
+	GLOBAL_MAX_SIZE = CACHE_GLOBAL_MAX_SIZE_BYTES;
+	LOW_HIT_RATE_THRESHOLD = CACHE_LOW_HIT_RATE_THRESHOLD;
+	caches = /* @__PURE__ */ new Map();
+	constructor() {
+		logger.info("UnifiedCacheManager initialized");
+	}
+	/** @deprecated Use constructor injection. Kept for backward compatibility. */
+	static getInstance() {
+		if (!this.instance) this.instance = new UnifiedCacheManager();
+		return this.instance;
+	}
+	registerCache(cache) {
+		this.caches.set(cache.name, cache);
+		logger.info(`Registered cache: ${cache.name}`);
+	}
+	unregisterCache(name) {
+		this.caches.delete(name);
+		logger.info(`Unregistered cache: ${name}`);
+	}
+	async getGlobalStats() {
+		let totalEntries = 0;
+		let totalSize = 0;
+		let totalHits = 0;
+		let totalMisses = 0;
+		const cacheStats = [];
+		for (const [name, cache] of this.caches) try {
+			const stats = await cache.getStats();
+			totalEntries += stats.entries;
+			totalSize += stats.size;
+			totalHits += stats.hits || 0;
+			totalMisses += stats.misses || 0;
+			cacheStats.push({
+				name,
+				entries: stats.entries,
+				size: stats.size,
+				sizeMB: (stats.size / 1024 / 1024).toFixed(2),
+				hitRate: stats.hitRate,
+				ttl: stats.ttl
+			});
+		} catch (error) {
+			logger.error(`Failed to get stats for cache ${name}:`, error);
+		}
+		const hitRate = totalHits + totalMisses > 0 ? totalHits / (totalHits + totalMisses) : 0;
+		const recommendations = this.generateRecommendations(totalSize, hitRate, cacheStats);
+		return {
+			totalEntries,
+			totalSize,
+			totalSizeMB: (totalSize / 1024 / 1024).toFixed(2),
+			hitRate,
+			caches: cacheStats,
+			recommendations
+		};
+	}
+	async smartCleanup(targetSize) {
+		const target = targetSize || this.GLOBAL_MAX_SIZE * .7;
+		const beforeStats = await this.getGlobalStats();
+		const beforeSize = beforeStats.totalSize;
+		if (beforeSize <= target) {
+			logger.info("No cleanup needed");
+			return {
+				before: beforeSize,
+				after: beforeSize,
+				freed: 0,
+				freedPercentage: 0
+			};
+		}
+		logger.info(`Smart cleanup: current ${beforeStats.totalSizeMB}MB, target ${(target / 1024 / 1024).toFixed(2)}MB`);
+		await this.cleanupExpired();
+		let currentStats = await this.getGlobalStats();
+		if (currentStats.totalSize <= target) return this.calculateCleanupResult(beforeSize, currentStats.totalSize);
+		await this.cleanupLowHitRate();
+		currentStats = await this.getGlobalStats();
+		if (currentStats.totalSize <= target) return this.calculateCleanupResult(beforeSize, currentStats.totalSize);
+		await this.cleanupLargeItems();
+		const afterStats = await this.getGlobalStats();
+		return this.calculateCleanupResult(beforeSize, afterStats.totalSize);
+	}
+	async cleanupExpired() {
+		logger.info("Cleaning up expired data...");
+		for (const [name, cache] of this.caches) if (cache.cleanup) try {
+			await cache.cleanup();
+			logger.debug(`Cleaned up expired data in ${name}`);
+		} catch (error) {
+			logger.error(`Failed to cleanup ${name}:`, error);
+		}
+	}
+	async cleanupLowHitRate() {
+		logger.info("Cleaning up low hit rate caches...");
+		const stats = await this.getGlobalStats();
+		const avgHitRate = stats.hitRate;
+		for (const cacheStats of stats.caches) if (cacheStats.hitRate !== void 0 && cacheStats.hitRate < avgHitRate * this.LOW_HIT_RATE_THRESHOLD) {
+			const cache = this.caches.get(cacheStats.name);
+			/* v8 ignore next */
+			if (cache?.clear) try {
+				await cache.clear();
+				logger.info(`Cleared low hit rate cache: ${cacheStats.name} (${(cacheStats.hitRate * 100).toFixed(1)}%)`);
+			} catch (error) {
+				logger.error(`Failed to clear ${cacheStats.name}:`, error);
+			}
+		}
+	}
+	async cleanupLargeItems() {
+		logger.info("Cleaning up large caches...");
+		const sortedCaches = (await this.getGlobalStats()).caches.toSorted((a, b) => b.size - a.size);
+		for (const cacheStats of sortedCaches.slice(0, 2)) {
+			const cache = this.caches.get(cacheStats.name);
+			/* v8 ignore next */
+			if (cache?.clear) try {
+				await cache.clear();
+				logger.info(`Cleared large cache: ${cacheStats.name} (${cacheStats.sizeMB}MB)`);
+			} catch (error) {
+				logger.error(`Failed to clear ${cacheStats.name}:`, error);
+			}
+		}
+	}
+	calculateCleanupResult(before, after) {
+		const freed = before - after;
+		const freedPercentage = Math.round(freed / this.GLOBAL_MAX_SIZE * 100);
+		logger.info(`Cleanup complete! Freed ${(freed / 1024 / 1024).toFixed(2)}MB (${freedPercentage}%). Usage: ${(after / 1024 / 1024).toFixed(2)}MB/${(this.GLOBAL_MAX_SIZE / 1024 / 1024).toFixed(0)}MB`);
+		return {
+			before,
+			after,
+			freed,
+			freedPercentage
+		};
+	}
+	async clearAll() {
+		logger.info("Clearing all caches...");
+		for (const [name, cache] of this.caches)
+ /* v8 ignore next */
+		if (cache.clear) try {
+			await cache.clear();
+			logger.info(`Cleared cache: ${name}`);
+		} catch (error) {
+			logger.error(`Failed to clear ${name}:`, error);
+		}
+		logger.success("All caches cleared");
+	}
+	async preheat(urls) {
+		logger.info(`Preheating cache for ${urls.length} URLs...`);
+		logger.info("Cache preheat completed");
+	}
+	generateRecommendations(totalSize, hitRate, cacheStats) {
+		const recommendations = [];
+		const sizeRatio = totalSize / this.GLOBAL_MAX_SIZE;
+		if (sizeRatio >= .9) recommendations.push(" CRITICAL: Cache size at 90%. Run smart_cache_cleanup immediately!");
+		else if (sizeRatio >= .7) recommendations.push("WARNING: Cache size at 70%. Consider cleanup soon.");
+		else if (sizeRatio >= .5) recommendations.push("INFO: Cache size at 50%. Monitor usage.");
+		if (hitRate < .3) recommendations.push(" Low cache hit rate (<30%). Consider adjusting TTL or cache strategy.");
+		else if (hitRate > .7) recommendations.push(" Good cache hit rate (>70%). Cache is working well.");
+		for (const cache of cacheStats) {
+			const cacheRatio = cache.size / totalSize;
+			if (cacheRatio > .5) recommendations.push(` ${cache.name} uses ${Math.round(cacheRatio * 100)}% of total cache. Consider cleanup.`);
+			if (cache.hitRate !== void 0 && cache.hitRate < .2) recommendations.push(` ${cache.name} has low hit rate (${(cache.hitRate * 100).toFixed(1)}%). Consider disabling or adjusting.`);
+		}
+		if (recommendations.length === 0) recommendations.push(" Cache health is good. No action needed.");
+		return recommendations;
+	}
+};
+//#endregion
+//#region src/utils/artifactRetention.ts
+const DAY_MS = 1440 * 60 * 1e3;
+function getArtifactRetentionConfig(env = process.env) {
+	const retentionDays = Math.max(0, parseInt(env.MCP_ARTIFACT_RETENTION_DAYS ?? "0", 10) || 0);
+	const maxTotalMb = Math.max(0, parseInt(env.MCP_ARTIFACT_MAX_TOTAL_MB ?? "0", 10) || 0);
+	const cleanupIntervalMinutes = Math.max(0, parseInt(env.MCP_ARTIFACT_CLEANUP_INTERVAL_MINUTES ?? "0", 10) || 0);
+	const cleanupOnStart = ["1", "true"].includes((env.MCP_ARTIFACT_CLEANUP_ON_START ?? "").toLowerCase());
+	return {
+		enabled: retentionDays > 0 || maxTotalMb > 0,
+		retentionDays,
+		maxTotalBytes: maxTotalMb * 1024 * 1024,
+		cleanupOnStart,
+		cleanupIntervalMinutes
+	};
+}
+async function cleanupArtifacts(options) {
+	const envConfig = getArtifactRetentionConfig();
+	const config = {
+		...envConfig,
+		retentionDays: options?.retentionDays ?? envConfig.retentionDays,
+		maxTotalBytes: options?.maxTotalBytes ?? envConfig.maxTotalBytes
+	};
+	const now = options?.now ?? Date.now();
+	const dryRun = options?.dryRun ?? false;
+	const directories = options?.directories ?? getManagedArtifactDirectories();
+	const cutoff = config.retentionDays > 0 ? now - config.retentionDays * DAY_MS : 0;
+	let scannedFiles = 0;
+	let removedFiles = 0;
+	let removedBytes = 0;
+	let removedByAge = 0;
+	let removedBySize = 0;
+	const remaining = [];
+	const removedSample = [];
+	const root = getProjectRoot();
+	const pendingRemovals = [];
+	function scheduleRemoval(path) {
+		pendingRemovals.push(rm(path, { force: true }).then(() => void 0).catch(() => void 0));
+	}
+	for (const directory of directories) await walkAndProcess(directory, root, cutoff, dryRun, (entry) => {
+		scannedFiles++;
+		if (cutoff > 0 && entry.mtimeMs < cutoff) {
+			removedFiles++;
+			removedBytes += entry.size;
+			removedByAge += entry.size;
+			if (removedSample.length < 20) removedSample.push(entry.relativePath);
+			if (!dryRun) scheduleRemoval(entry.path);
+		} else remaining.push(entry);
+	});
+	if (config.maxTotalBytes > 0) {
+		let totalBytes = remaining.reduce((sum, entry) => sum + entry.size, 0);
+		if (totalBytes > config.maxTotalBytes) {
+			remaining.sort((a, b) => a.mtimeMs - b.mtimeMs);
+			let i = 0;
+			while (i < remaining.length && totalBytes > config.maxTotalBytes) {
+				const entry = remaining[i];
+				totalBytes -= entry.size;
+				removedFiles++;
+				removedBytes += entry.size;
+				removedBySize += entry.size;
+				if (removedSample.length < 20) removedSample.push(entry.relativePath);
+				if (!dryRun) scheduleRemoval(entry.path);
+				i++;
+			}
+			remaining.splice(0, i);
+		}
+	}
+	if (!dryRun) {
+		await Promise.all(pendingRemovals);
+		await Promise.all(directories.map((dir) => pruneEmptyDirectories(dir)));
+	}
+	return {
+		success: true,
+		scannedFiles,
+		removedFiles,
+		removedBytes,
+		removedByAge,
+		removedBySize,
+		remainingFiles: remaining.length,
+		remainingBytes: remaining.reduce((sum, entry) => sum + entry.size, 0),
+		dryRun,
+		directories,
+		removedSample,
+		config
+	};
+}
+function startArtifactRetentionScheduler() {
+	const config = getArtifactRetentionConfig();
+	if (!config.enabled || config.cleanupIntervalMinutes <= 0) return null;
+	const handle = setInterval(() => {
+		/* v8 ignore next */
+		cleanupArtifacts().then((result) => {
+			if (result.removedFiles > 0) logger.info(`[artifacts] retention cleanup removed ${result.removedFiles} files (${result.removedBytes} bytes)`);
+		}).catch((error) => {
+			logger.warn("[artifacts] retention cleanup failed", error);
+		});
+	}, config.cleanupIntervalMinutes * 60 * 1e3);
+	handle.unref();
+	return () => clearInterval(handle);
+}
+function getManagedArtifactDirectories() {
+	const projectRoot = getProjectRoot();
+	const cwdDebuggerSessionsDir = resolve(process.cwd(), "debugger-sessions");
+	const projectDebuggerSessionsDir = resolve(projectRoot, "debugger-sessions");
+	const directories = new Set([
+		getArtifactsRoot(),
+		getConfig().paths.screenshotDir,
+		getDebuggerSessionsDir(),
+		cwdDebuggerSessionsDir,
+		projectDebuggerSessionsDir
+	]);
+	for (const category of [
+		"wasm",
+		"traces",
+		"profiles",
+		"dumps",
+		"reports",
+		"har",
+		"sessions",
+		"tmp"
+	]) directories.add(getArtifactDir(category));
+	return [...directories];
+}
+async function walkAndProcess(directory, root, cutoff, dryRun, onFile) {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const entryPath = join(directory, entry.name);
+		if (entry.isDirectory()) await walkAndProcess(entryPath, root, cutoff, dryRun, onFile);
+		else if (entry.isFile()) {
+			let info;
+			try {
+				info = await stat(entryPath);
+			} catch {
+				continue;
+			}
+			onFile({
+				path: entryPath,
+				relativePath: relativePathFromRoot(root, entryPath),
+				size: info.size,
+				mtimeMs: info.mtimeMs
+			});
+		}
+	}
+}
+async function pruneEmptyDirectories(directory) {
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	await Promise.all(entries.filter((entry) => entry.isDirectory()).map((entry) => pruneEmptyDirectories(join(directory, entry.name))));
+	try {
+		if ((await readdir(directory)).length === 0) await rm(directory, {
+			recursive: true,
+			force: true
+		});
+	} catch {}
+}
+function relativePathFromRoot(root, path) {
+	return path.startsWith(root) ? path.slice(root.length).replace(/^[\\/]/, "").replace(/\\/g, "/") : path.replace(/\\/g, "/");
+}
+//#endregion
+export { TokenBudgetManager as a, UnifiedCacheManager as i, getArtifactRetentionConfig as n, startArtifactRetentionScheduler as r, cleanupArtifacts as t };

package/dist/artifacts-DkfosXH3.mjs

@@ -0,0 +1,59 @@
+import { t as __exportAll } from "./chunk-CjcI7cDX.mjs";
+import { i as getProjectRoot } from "./outputPaths-um7lCRY3.mjs";
+import { isAbsolute, normalize, relative, resolve, sep } from "node:path";
+import { mkdir } from "node:fs/promises";
+//#region src/utils/artifacts.ts
+/**
+* Unified artifact output management.
+* Ensures all tool outputs go to well-structured directories with consistent naming.
+*/
+var artifacts_exports = /* @__PURE__ */ __exportAll({
+	getArtifactDir: () => getArtifactDir,
+	getArtifactsRoot: () => getArtifactsRoot,
+	resolveArtifactPath: () => resolveArtifactPath
+});
+const ARTIFACT_BASE = "artifacts";
+/**
+* Generate a timestamped artifact path.
+*
+* @param category - Artifact subdirectory (wasm, traces, etc.)
+* @param toolName - Tool that produces this artifact
+* @param target - Target identifier (e.g., module name, URL hash)
+* @param ext - File extension (without dot)
+* @returns { absolutePath, displayPath }
+*/
+async function resolveArtifactPath(options) {
+	const { category, toolName, target, ext, customDir } = options;
+	const root = getProjectRoot();
+	const dir = customDir ? resolve(root, customDir) : resolve(root, ARTIFACT_BASE, category);
+	const relativeDir = relative(normalize(root), normalize(dir));
+	if (relativeDir === ".." || relativeDir.startsWith(`..${sep}`) || isAbsolute(relativeDir)) throw new Error(`Path traversal blocked: artifact directory "${customDir}" escapes project root`);
+	await mkdir(dir, { recursive: true });
+	const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+	const shortId = Math.random().toString(36).substring(2, 8);
+	const absolutePath = resolve(dir, `${sanitizeFilename(toolName)}${target ? `-${sanitizeFilename(target)}` : ""}-${ts}-${shortId}.${ext.replace(/^\./, "")}`);
+	return {
+		absolutePath,
+		displayPath: relative(root, absolutePath).replace(/\\/g, "/")
+	};
+}
+/**
+* Get the artifacts root directory.
+*/
+function getArtifactsRoot() {
+	return resolve(getProjectRoot(), ARTIFACT_BASE);
+}
+/**
+* Get a specific artifact category directory.
+*/
+function getArtifactDir(category) {
+	return resolve(getProjectRoot(), ARTIFACT_BASE, category);
+}
+/**
+* Sanitize a string for use as a filename component.
+*/
+function sanitizeFilename(name) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").substring(0, 60);
+}
+//#endregion
+export { resolveArtifactPath as i, getArtifactDir as n, getArtifactsRoot as r, artifacts_exports as t };

package/dist/authorization-schema-DRqyJMSk.mjs

@@ -0,0 +1,31 @@
+//#region src/server/domains/network/authorization-schema.ts
+const networkAuthorizationSchema = {
+	allowedHosts: {
+		type: "array",
+		items: { type: "string" },
+		description: "Exact hostnames or IP literals allowed for this request."
+	},
+	allowedCidrs: {
+		type: "array",
+		items: { type: "string" },
+		description: "Explicit CIDR ranges allowed for this request."
+	},
+	allowPrivateNetwork: {
+		type: "boolean",
+		description: "Allow access to private or reserved network targets, but only when the resolved host matches allowedHosts or allowedCidrs."
+	},
+	allowInsecureHttp: {
+		type: "boolean",
+		description: "Allow plain HTTP access to explicitly authorized targets in allowedHosts or allowedCidrs."
+	},
+	expiresAt: {
+		type: "string",
+		description: "Optional ISO-8601 expiry time for this authorization."
+	},
+	reason: {
+		type: "string",
+		description: "Short audit note describing why this authorization is needed."
+	}
+};
+//#endregion
+export { networkAuthorizationSchema as t };