miladyai 2.0.0-alpha.27

package/dist/api/knowledge-routes.js

@@ -0,0 +1,534 @@
+import { isBlockedPrivateOrLinkLocalIp, normalizeHostLike } from "../security/network-policy.js";
+import { parseClampedFloat, parsePositiveInteger } from "../utils/number-parsing.js";
+import { lookup } from "node:dns/promises";
+import net from "node:net";
+
+//#region src/api/knowledge-routes.ts
+const FRAGMENT_COUNT_BATCH_SIZE = 500;
+const MAX_URL_IMPORT_BYTES = 10 * 1024 * 1024;
+const MAX_YOUTUBE_WATCH_PAGE_BYTES = 2 * 1024 * 1024;
+const MAX_YOUTUBE_TRANSCRIPT_BYTES = 10 * 1024 * 1024;
+const URL_FETCH_TIMEOUT_MS = 15e3;
+const BLOCKED_HOST_LITERALS = new Set(["localhost", "metadata.google.internal"]);
+function toSafeNumber(value, fallback) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+function hasUuidId(memory) {
+	return typeof memory.id === "string" && memory.id.length > 0;
+}
+function hasUuidIdAndCreatedAt(memory) {
+	return hasUuidId(memory) && typeof memory.createdAt === "number";
+}
+async function countKnowledgeFragmentsForDocument(knowledgeService, roomId, documentId) {
+	let offset = 0;
+	let fragmentCount = 0;
+	while (true) {
+		const knowledgeBatch = await knowledgeService.getMemories({
+			tableName: "knowledge",
+			roomId,
+			count: FRAGMENT_COUNT_BATCH_SIZE,
+			offset
+		});
+		if (knowledgeBatch.length === 0) break;
+		fragmentCount += knowledgeBatch.filter((memory) => {
+			return memory.metadata?.documentId === documentId;
+		}).length;
+		if (knowledgeBatch.length < FRAGMENT_COUNT_BATCH_SIZE) break;
+		offset += FRAGMENT_COUNT_BATCH_SIZE;
+	}
+	return fragmentCount;
+}
+async function mapKnowledgeFragmentsByDocumentId(knowledgeService, roomId, documentIds) {
+	const fragmentCounts = /* @__PURE__ */ new Map();
+	const trackedDocumentIds = new Set(documentIds);
+	for (const documentId of trackedDocumentIds) fragmentCounts.set(documentId, 0);
+	if (trackedDocumentIds.size === 0) return fragmentCounts;
+	let offset = 0;
+	while (true) {
+		const knowledgeBatch = await knowledgeService.getMemories({
+			tableName: "knowledge",
+			roomId,
+			count: FRAGMENT_COUNT_BATCH_SIZE,
+			offset
+		});
+		if (knowledgeBatch.length === 0) break;
+		for (const memory of knowledgeBatch) {
+			const documentId = memory.metadata?.documentId;
+			if (typeof documentId === "string" && trackedDocumentIds.has(documentId)) {
+				const currentCount = fragmentCounts.get(documentId) ?? 0;
+				fragmentCounts.set(documentId, currentCount + 1);
+			}
+		}
+		if (knowledgeBatch.length < FRAGMENT_COUNT_BATCH_SIZE) break;
+		offset += FRAGMENT_COUNT_BATCH_SIZE;
+	}
+	return fragmentCounts;
+}
+async function listKnowledgeFragmentsForDocument(knowledgeService, roomId, documentId) {
+	let offset = 0;
+	const fragmentIds = [];
+	while (true) {
+		const knowledgeBatch = await knowledgeService.getMemories({
+			tableName: "knowledge",
+			roomId,
+			count: FRAGMENT_COUNT_BATCH_SIZE,
+			offset
+		});
+		for (const memory of knowledgeBatch) if (memory.metadata?.documentId === documentId && hasUuidId(memory)) fragmentIds.push(memory.id);
+		if (knowledgeBatch.length < FRAGMENT_COUNT_BATCH_SIZE) break;
+		offset += FRAGMENT_COUNT_BATCH_SIZE;
+	}
+	return fragmentIds;
+}
+async function getKnowledgeService(runtime) {
+	if (!runtime) return null;
+	let service = runtime.getService("knowledge");
+	if (service) return service;
+	try {
+		const servicePromise = runtime.getServiceLoadPromise("knowledge");
+		const timeout = new Promise((_resolve, reject) => {
+			setTimeout(() => {
+				reject(/* @__PURE__ */ new Error("Knowledge service load timeout (10s)"));
+			}, 1e4);
+		});
+		await Promise.race([servicePromise, timeout]);
+		service = runtime.getService("knowledge");
+	} catch {
+		return null;
+	}
+	return service;
+}
+function isBlockedIp(ip) {
+	return isBlockedPrivateOrLinkLocalIp(ip);
+}
+async function resolveUrlSafetyRejection(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return "Invalid URL format";
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "Only http:// and https:// URLs are allowed";
+	const hostname = normalizeHostLike(parsed.hostname);
+	if (!hostname) return "URL hostname is required";
+	if (BLOCKED_HOST_LITERALS.has(hostname)) return `URL host "${hostname}" is blocked for security reasons`;
+	if (net.isIP(hostname)) {
+		if (isBlockedIp(hostname)) return `URL host "${hostname}" is blocked for security reasons`;
+		return null;
+	}
+	let addresses;
+	try {
+		const resolved = await lookup(hostname, { all: true });
+		addresses = Array.isArray(resolved) ? resolved : [resolved];
+	} catch {
+		return `Could not resolve URL host "${hostname}"`;
+	}
+	if (addresses.length === 0) return `Could not resolve URL host "${hostname}"`;
+	for (const entry of addresses) if (isBlockedIp(entry.address)) return `URL host "${hostname}" resolves to blocked address ${entry.address}`;
+	return null;
+}
+function isYouTubeUrl(url) {
+	return /^https?:\/\/(www\.)?(youtube\.com|youtu\.be)/.test(url);
+}
+function extractYouTubeVideoId(url) {
+	const shortMatch = url.match(/youtu\.be\/([a-zA-Z0-9_-]{11})/);
+	if (shortMatch) return shortMatch[1];
+	const watchMatch = url.match(/[?&]v=([a-zA-Z0-9_-]{11})/);
+	if (watchMatch) return watchMatch[1];
+	const embedMatch = url.match(/\/embed\/([a-zA-Z0-9_-]{11})/);
+	if (embedMatch) return embedMatch[1];
+	const vMatch = url.match(/\/v\/([a-zA-Z0-9_-]{11})/);
+	if (vMatch) return vMatch[1];
+	return null;
+}
+async function fetchYouTubeTranscript(videoId) {
+	const response = await fetchWithTimeout(`https://www.youtube.com/watch?v=${videoId}`, { headers: {
+		"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+		"Accept-Language": "en-US,en;q=0.9"
+	} });
+	if (!response.ok) return null;
+	const html = new TextDecoder().decode(await readResponseBodyWithLimit(response, MAX_YOUTUBE_WATCH_PAGE_BYTES));
+	if (!html.match(/"captions":\s*\{[^}]*"playerCaptionsTracklistRenderer":\s*\{[^}]*"captionTracks":\s*\[([^\]]+)\]/)) {
+		if (!html.match(/"captionTracks":\s*\[([^\]]+)\]/)) return null;
+	}
+	const baseUrlMatch = html.match(/"baseUrl":\s*"(https:\/\/www\.youtube\.com\/api\/timedtext[^"]+)"/);
+	if (!baseUrlMatch) return null;
+	const transcriptResponse = await fetchWithTimeout(baseUrlMatch[1].replace(/\\u0026/g, "&").replace(/\\\//g, "/"), {});
+	if (!transcriptResponse.ok) return null;
+	const textMatches = new TextDecoder().decode(await readResponseBodyWithLimit(transcriptResponse, MAX_YOUTUBE_TRANSCRIPT_BYTES)).matchAll(/<text[^>]*>([^<]*)<\/text>/g);
+	const segments = [];
+	for (const match of textMatches) {
+		const text = match[1].replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").trim();
+		if (text) segments.push(text);
+	}
+	if (segments.length === 0) return null;
+	return segments.join(" ");
+}
+function readContentLengthHeader(response) {
+	const raw = response.headers.get("content-length");
+	if (!raw) return null;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return null;
+	return parsed;
+}
+function isAbortError(error) {
+	return error instanceof DOMException ? error.name === "AbortError" : error instanceof Error && error.name === "AbortError";
+}
+async function fetchWithTimeout(input, init, timeoutMs = URL_FETCH_TIMEOUT_MS) {
+	const controller = new AbortController();
+	const upstreamSignal = init.signal;
+	const onAbort = () => controller.abort();
+	if (upstreamSignal) if (upstreamSignal.aborted) controller.abort();
+	else upstreamSignal.addEventListener("abort", onAbort, { once: true });
+	const timeoutHandle = setTimeout(() => {
+		controller.abort();
+	}, timeoutMs);
+	try {
+		return await fetch(input, {
+			...init,
+			signal: controller.signal
+		});
+	} catch (error) {
+		if (isAbortError(error)) throw new Error(`URL fetch timed out after ${timeoutMs}ms`);
+		throw error;
+	} finally {
+		clearTimeout(timeoutHandle);
+		if (upstreamSignal) upstreamSignal.removeEventListener("abort", onAbort);
+	}
+}
+async function readResponseBodyWithLimit(response, maxBytes) {
+	const declaredLength = readContentLengthHeader(response);
+	if (declaredLength !== null && declaredLength > maxBytes) throw new Error(`URL content exceeds maximum size of ${maxBytes} bytes`);
+	if (!response.body) {
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		if (bytes.byteLength > maxBytes) throw new Error(`URL content exceeds maximum size of ${maxBytes} bytes`);
+		return bytes;
+	}
+	const reader = response.body.getReader();
+	const chunks = [];
+	let totalBytes = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			totalBytes += value.byteLength;
+			if (totalBytes > maxBytes) throw new Error(`URL content exceeds maximum size of ${maxBytes} bytes`);
+			chunks.push(value);
+		}
+	} catch (err) {
+		try {
+			await reader.cancel(err);
+		} catch {}
+		throw err;
+	} finally {
+		reader.releaseLock();
+	}
+	const output = new Uint8Array(totalBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		output.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return output;
+}
+async function fetchUrlContent(url) {
+	if (isYouTubeUrl(url)) {
+		const videoId = extractYouTubeVideoId(url);
+		if (!videoId) throw new Error("Invalid YouTube URL: could not extract video ID");
+		const transcript = await fetchYouTubeTranscript(videoId);
+		if (!transcript) throw new Error("Could not fetch YouTube transcript. The video may not have captions available.");
+		return {
+			content: transcript,
+			contentType: "text/plain",
+			filename: `youtube-${videoId}-transcript.txt`
+		};
+	}
+	const response = await fetchWithTimeout(url, {
+		redirect: "manual",
+		headers: { "User-Agent": "Mozilla/5.0 (compatible; Milaidy/1.0; +https://milaidy.ai)" }
+	});
+	if (response.status >= 300 && response.status < 400) throw new Error("URL redirects are not allowed");
+	if (!response.ok) throw new Error(`Failed to fetch URL: ${response.status} ${response.statusText}`);
+	const contentType = response.headers.get("content-type") || "application/octet-stream";
+	const pathSegments = new URL(url).pathname.split("/");
+	const encodedFilename = pathSegments[pathSegments.length - 1] || "document";
+	const filename = decodeURIComponent(encodedFilename);
+	const buffer = await readResponseBodyWithLimit(response, MAX_URL_IMPORT_BYTES);
+	if (contentType.startsWith("application/pdf") || contentType.startsWith("application/msword") || contentType.startsWith("application/vnd.openxmlformats-officedocument") || contentType.startsWith("image/")) return {
+		content: Buffer.from(buffer).toString("base64"),
+		contentType,
+		filename
+	};
+	return {
+		content: new TextDecoder().decode(buffer),
+		contentType,
+		filename
+	};
+}
+async function handleKnowledgeRoutes(ctx) {
+	const { req, res, method, pathname, url, runtime, json, error, readJsonBody } = ctx;
+	if (!pathname.startsWith("/api/knowledge")) return false;
+	const knowledgeService = await getKnowledgeService(runtime);
+	if (!knowledgeService) {
+		error(res, "Knowledge service is not available. Agent may not be running.", 503);
+		return true;
+	}
+	if (!runtime?.agentId) {
+		error(res, "Agent runtime is not available", 503);
+		return true;
+	}
+	const agentId = runtime.agentId;
+	if (method === "GET" && pathname === "/api/knowledge/stats") {
+		json(res, {
+			documentCount: await knowledgeService.countMemories({
+				tableName: "documents",
+				roomId: agentId,
+				unique: false
+			}),
+			fragmentCount: await knowledgeService.countMemories({
+				tableName: "knowledge",
+				roomId: agentId,
+				unique: false
+			}),
+			agentId
+		});
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/knowledge/documents") {
+		const limit = parsePositiveInteger(url.searchParams.get("limit"), 100);
+		const offset = parsePositiveInteger(url.searchParams.get("offset"), 0);
+		const documents = await knowledgeService.getMemories({
+			tableName: "documents",
+			roomId: agentId,
+			count: limit,
+			offset: offset > 0 ? offset : void 0
+		});
+		const fragmentCounts = await mapKnowledgeFragmentsByDocumentId(knowledgeService, agentId, documents.filter(hasUuidId).map((doc) => doc.id));
+		const cleanedDocuments = documents.map((doc) => {
+			const metadata = doc.metadata;
+			const documentId = hasUuidId(doc) ? doc.id : null;
+			return {
+				id: doc.id,
+				filename: metadata?.filename || metadata?.title || "Untitled",
+				contentType: metadata?.fileType || metadata?.contentType || "unknown",
+				fileSize: toSafeNumber(metadata?.fileSize, 0),
+				createdAt: toSafeNumber(doc.createdAt, 0),
+				fragmentCount: documentId !== null && fragmentCounts.has(documentId) ? fragmentCounts.get(documentId) ?? 0 : 0,
+				source: metadata?.source || "upload",
+				url: metadata?.url
+			};
+		});
+		json(res, {
+			documents: cleanedDocuments,
+			total: cleanedDocuments.length,
+			limit,
+			offset: offset > 0 ? offset : 0
+		});
+		return true;
+	}
+	const docIdMatch = /^\/api\/knowledge\/documents\/([^/]+)$/.exec(pathname);
+	if (method === "GET" && docIdMatch) {
+		const documentId = decodeURIComponent(docIdMatch[1]);
+		const document = (await knowledgeService.getMemories({
+			tableName: "documents",
+			roomId: agentId,
+			count: 1e4
+		})).find((d) => d.id === documentId);
+		if (!document) {
+			error(res, "Document not found", 404);
+			return true;
+		}
+		const fragmentCount = await countKnowledgeFragmentsForDocument(knowledgeService, agentId, documentId);
+		const metadata = document.metadata;
+		json(res, { document: {
+			id: document.id,
+			filename: metadata?.filename || metadata?.title || "Untitled",
+			contentType: metadata?.fileType || metadata?.contentType || "unknown",
+			fileSize: toSafeNumber(metadata?.fileSize, 0),
+			createdAt: toSafeNumber(document.createdAt, 0),
+			fragmentCount,
+			source: metadata?.source || "upload",
+			url: metadata?.url,
+			content: document.content
+		} });
+		return true;
+	}
+	if (method === "DELETE" && docIdMatch) {
+		const documentId = decodeURIComponent(docIdMatch[1]);
+		const fragmentIds = await listKnowledgeFragmentsForDocument(knowledgeService, agentId, documentId);
+		for (const fragmentId of fragmentIds) await knowledgeService.deleteMemory(fragmentId);
+		await knowledgeService.deleteMemory(documentId);
+		json(res, {
+			ok: true,
+			deletedFragments: fragmentIds.length
+		});
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/knowledge/documents") {
+		const body = await readJsonBody(req, res);
+		if (!body) return true;
+		if (!body.content || !body.filename) {
+			error(res, "content and filename are required");
+			return true;
+		}
+		const result = await knowledgeService.addKnowledge({
+			agentId,
+			worldId: agentId,
+			roomId: agentId,
+			entityId: agentId,
+			clientDocumentId: "",
+			contentType: body.contentType || "text/plain",
+			originalFilename: body.filename,
+			content: body.content,
+			metadata: body.metadata
+		});
+		json(res, {
+			ok: true,
+			documentId: result.clientDocumentId,
+			fragmentCount: result.fragmentCount
+		});
+		return true;
+	}
+	if (method === "POST" && pathname === "/api/knowledge/documents/url") {
+		const body = await readJsonBody(req, res);
+		if (!body) return true;
+		if (!body.url?.trim()) {
+			error(res, "url is required");
+			return true;
+		}
+		const urlToFetch = body.url.trim();
+		const safetyRejection = await resolveUrlSafetyRejection(urlToFetch);
+		if (safetyRejection) {
+			error(res, safetyRejection);
+			return true;
+		}
+		let content;
+		let contentType;
+		let filename;
+		try {
+			({content, contentType, filename} = await fetchUrlContent(urlToFetch));
+		} catch (err) {
+			error(res, err instanceof Error ? err.message : "Failed to fetch URL content");
+			return true;
+		}
+		const result = await knowledgeService.addKnowledge({
+			agentId,
+			worldId: agentId,
+			roomId: agentId,
+			entityId: agentId,
+			clientDocumentId: "",
+			contentType,
+			originalFilename: filename,
+			content,
+			metadata: {
+				...body.metadata,
+				url: urlToFetch,
+				source: isYouTubeUrl(urlToFetch) ? "youtube" : "url"
+			}
+		});
+		json(res, {
+			ok: true,
+			documentId: result.clientDocumentId,
+			fragmentCount: result.fragmentCount,
+			filename,
+			contentType,
+			isYouTubeTranscript: isYouTubeUrl(urlToFetch)
+		});
+		return true;
+	}
+	if (method === "GET" && pathname === "/api/knowledge/search") {
+		const query = url.searchParams.get("q");
+		if (!query?.trim()) {
+			error(res, "Search query (q) is required");
+			return true;
+		}
+		const threshold = parseClampedFloat(url.searchParams.get("threshold"), {
+			fallback: .3,
+			min: 0,
+			max: 1
+		});
+		const limit = parsePositiveInteger(url.searchParams.get("limit"), 20);
+		const searchMessage = {
+			id: crypto.randomUUID(),
+			entityId: agentId,
+			agentId,
+			roomId: agentId,
+			content: { text: query.trim() },
+			createdAt: Date.now()
+		};
+		const filteredResults = (await knowledgeService.getKnowledge(searchMessage, { roomId: agentId })).filter((r) => (r.similarity ?? 0) >= threshold).slice(0, limit).map((r) => {
+			const meta = r.metadata;
+			return {
+				id: r.id,
+				text: r.content?.text || "",
+				similarity: r.similarity,
+				documentId: meta?.documentId,
+				documentTitle: meta?.filename || meta?.title || "",
+				position: meta?.position
+			};
+		});
+		json(res, {
+			query: query.trim(),
+			threshold,
+			results: filteredResults,
+			count: filteredResults.length
+		});
+		return true;
+	}
+	const fragmentsMatch = /^\/api\/knowledge\/fragments\/([^/]+)$/.exec(pathname);
+	if (method === "GET" && fragmentsMatch) {
+		const documentId = decodeURIComponent(fragmentsMatch[1]);
+		const allFragments = [];
+		let fragmentOffset = 0;
+		while (true) {
+			const fragmentBatch = await knowledgeService.getMemories({
+				tableName: "knowledge",
+				roomId: agentId,
+				count: FRAGMENT_COUNT_BATCH_SIZE,
+				offset: fragmentOffset
+			});
+			if (fragmentBatch.length === 0) break;
+			const matchingFragments = fragmentBatch.filter((fragment) => {
+				return fragment.metadata?.documentId === documentId;
+			});
+			for (const fragment of matchingFragments) {
+				if (!hasUuidIdAndCreatedAt(fragment)) continue;
+				const meta = fragment.metadata;
+				allFragments.push({
+					id: fragment.id,
+					text: fragment.content?.text || "",
+					position: meta?.position,
+					createdAt: fragment.createdAt
+				});
+			}
+			if (fragmentBatch.length < FRAGMENT_COUNT_BATCH_SIZE) break;
+			fragmentOffset += FRAGMENT_COUNT_BATCH_SIZE;
+		}
+		const documentFragments = allFragments.sort((a, b) => {
+			return (typeof a.position === "number" ? a.position : 0) - (typeof b.position === "number" ? b.position : 0);
+		}).map((f) => {
+			return {
+				id: f.id,
+				text: f.text,
+				position: f.position,
+				createdAt: f.createdAt
+			};
+		});
+		json(res, {
+			documentId,
+			fragments: documentFragments,
+			count: documentFragments.length
+		});
+		return true;
+	}
+	return false;
+}
+
+//#endregion
+export { handleKnowledgeRoutes };

package/dist/api/memory-bounds.js

@@ -0,0 +1,71 @@
+//#region src/api/memory-bounds.ts
+/**
+* Evict expired entries from a rate-limit map when it exceeds `threshold`.
+* Safe to call during iteration (Map spec permits deletion during for-of).
+*/
+function sweepExpiredEntries(map, now, threshold) {
+	if (map.size <= threshold) return;
+	for (const [k, v] of map) if (now > v.resetAt) map.delete(k);
+}
+/**
+* Evict the oldest conversation (by `updatedAt`) when the map exceeds `cap`.
+* Returns the evicted key, or null if no eviction was needed.
+*/
+function evictOldestConversation(map, cap) {
+	if (map.size <= cap) return null;
+	let oldestKey = null;
+	let oldestTime = Infinity;
+	for (const [k, v] of map) {
+		const t = new Date(v.updatedAt).getTime();
+		if (t < oldestTime) {
+			oldestTime = t;
+			oldestKey = k;
+		}
+	}
+	if (oldestKey) map.delete(oldestKey);
+	return oldestKey;
+}
+/**
+* Push an entry to a bounded buffer and batch-evict when the high-water
+* mark is reached.  Returns the current buffer length.
+*
+* @param buffer   - The array to push into.
+* @param entry    - The item to append.
+* @param highWater - Trigger eviction when `buffer.length` exceeds this.
+* @param evictCount - Number of oldest entries to remove on eviction.
+*/
+function pushWithBatchEvict(buffer, entry, highWater, evictCount) {
+	buffer.push(entry);
+	if (buffer.length > highWater) buffer.splice(0, evictCount);
+	return buffer.length;
+}
+/**
+* Retrieve a file from a bounded cache, reading from disk on miss.
+* Files larger than `fileSizeLimit` are never cached.
+*
+* @param cache         - The Map serving as the LRU-ish cache.
+* @param filePath      - Absolute path to the file.
+* @param mtimeMs       - File's last-modified time (for invalidation).
+* @param readFile      - Callback that reads the file (injected for testing).
+* @param maxEntries    - Maximum number of cached files.
+* @param fileSizeLimit - Maximum file size (bytes) eligible for caching.
+*/
+function getOrReadCachedFile(cache, filePath, mtimeMs, readFile, maxEntries, fileSizeLimit) {
+	const cached = cache.get(filePath);
+	if (cached && cached.mtimeMs === mtimeMs) return cached.body;
+	const body = readFile(filePath);
+	if (body.length <= fileSizeLimit) {
+		if (cache.size >= maxEntries) {
+			const firstKey = cache.keys().next().value;
+			if (firstKey !== void 0) cache.delete(firstKey);
+		}
+		cache.set(filePath, {
+			body,
+			mtimeMs
+		});
+	}
+	return body;
+}
+
+//#endregion
+export { evictOldestConversation, getOrReadCachedFile, pushWithBatchEvict, sweepExpiredEntries };

package/dist/api/models-routes.js

@@ -0,0 +1,28 @@
+//#region src/api/models-routes.ts
+async function handleModelsRoutes(ctx) {
+	const { res, method, pathname, url, json, providerCachePath, getOrFetchProvider, getOrFetchAllProviders, resolveModelsCacheDir, pathExists, readDir, unlinkFile, joinPath } = ctx;
+	if (method !== "GET" || pathname !== "/api/models") return false;
+	const force = url.searchParams.get("refresh") === "true";
+	const specificProvider = url.searchParams.get("provider");
+	if (specificProvider) {
+		if (force) try {
+			unlinkFile(providerCachePath(specificProvider));
+		} catch {}
+		json(res, {
+			provider: specificProvider,
+			models: await getOrFetchProvider(specificProvider, force)
+		});
+		return true;
+	}
+	if (force) try {
+		const dir = resolveModelsCacheDir();
+		if (pathExists(dir)) {
+			for (const file of readDir(dir)) if (file.endsWith(".json")) unlinkFile(joinPath(dir, file));
+		}
+	} catch {}
+	json(res, { providers: await getOrFetchAllProviders(force) });
+	return true;
+}
+
+//#endregion
+export { handleModelsRoutes };

package/dist/api/og-tracker.js

@@ -0,0 +1,36 @@
+import { resolveStateDir } from "../config/paths.js";
+import path from "node:path";
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+//#region src/api/og-tracker.ts
+/**
+* OG tracking code system.
+*
+* Silently writes a unique identifier to ~/.milady/.og on first run.
+* The code is a random UUID. A set of 100 "winning" codes can be
+* generated deterministically from a secret seed (in MiladyMaker scripts).
+* This file is planted now; whitelist eligibility is revealed in a future update.
+*/
+const OG_FILENAME = ".og";
+/**
+* Write a random tracking UUID to ~/.milady/.og if it does not already exist.
+* Called once during startup. Silent on failure.
+*/
+function initializeOGCode() {
+	const dir = resolveStateDir();
+	const filePath = path.join(dir, OG_FILENAME);
+	if (fs.existsSync(filePath)) return;
+	const code = crypto.randomUUID();
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	fs.writeFileSync(filePath, code, {
+		encoding: "utf-8",
+		mode: 384
+	});
+}
+
+//#endregion
+export { initializeOGCode };