pi-webfind 0.5.0

package/lib/adapters.ts

@@ -0,0 +1,228 @@
+/**
+ * Site adapters — route known URL shapes to a cheaper, cleaner source
+ * instead of scraping HTML. Each adapter returns markdown or null
+ * (null = no adapter / adapter failed → caller falls back to generic fetch).
+ *
+ * All free, no keys (GitHub optionally honours GITHUB_TOKEN for rate limits).
+ */
+import { getJson } from "./apis.ts";
+
+const UA = "pi-webfind/0.5 (free web research toolkit for pi coding agent; +https://github.com/jawwadzafar/pi-webfind)";
+
+async function getText(url: string, signal?: AbortSignal, headers?: Record<string, string>): Promise<string> {
+	const timeout = AbortSignal.timeout(20_000);
+	const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+	const res = await fetch(url, {
+		headers: { "User-Agent": UA, Accept: "text/plain, text/markdown, */*", ...headers },
+		signal: combined,
+		redirect: "follow",
+	});
+	if (!res.ok) throw new Error(`HTTP ${res.status} from ${new URL(url).host}`);
+	return res.text();
+}
+
+export interface AdapterResult {
+	text: string;
+	source: string; // e.g. "github-api"
+}
+
+type Adapter = (url: URL, signal?: AbortSignal) => Promise<AdapterResult | null>;
+
+// ------------------------------------------------------------------- github
+
+function ghHeaders(): Record<string, string> {
+	const token = process.env.GITHUB_TOKEN;
+	return token ? { Authorization: `Bearer ${token}`, Accept: "application/vnd.github+json" } : { Accept: "application/vnd.github+json" };
+}
+
+const githubAdapter: Adapter = async (url, signal) => {
+	const parts = url.pathname.split("/").filter(Boolean); // [o, r, (blob|tree|issues|pull), ...]
+	if (parts.length < 2) return null;
+	const [owner, repo, kind, ...rest] = parts;
+
+	// raw file: /blob/{ref}/{path...} or /raw/{ref}/{path...}
+	if ((kind === "blob" || kind === "raw") && rest.length >= 2) {
+		const [, ref, ...path] = [kind, rest[0], ...rest.slice(1)];
+		const raw = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path.join("/")}`;
+		const text = await getText(raw, signal);
+		return { text: text.slice(0, 200_000), source: "github-raw" };
+	}
+
+	// issue / pull: API → markdown
+	if (kind === "issues" || kind === "pull") {
+		const num = Number(rest[0]);
+		if (!num) return null;
+		const isPr = kind === "pull";
+		const base = `https://api.github.com/repos/${owner}/${repo}/${isPr ? "pulls" : "issues"}/${num}`;
+		const item = await getJson<any>(base, signal, ghHeaders());
+		let md = `# ${item.title ?? `${owner}/${repo}#${num}`}\n\n${isPr && item.message ? "" : ""}${item.body ?? "(no body)"}\n`;
+		md = md.replace(/^(# .*\n\n)+/, `# ${item.title}\n\n`); // collapse stray dupes
+		const comments = await getJson<any[]>(`https://api.github.com/repos/${owner}/${repo}/issues/${num}/comments?per_page=30`, signal, ghHeaders()).catch(() => []);
+		if (Array.isArray(comments) && comments.length > 0) {
+			md += `\n---\n\n## Comments\n\n` + comments
+				.map((c) => `**${c.user?.login ?? "?"}** (${(c.created_at ?? "").slice(0, 10)}):\n\n${c.body ?? ""}`)
+				.join("\n\n---\n\n");
+		}
+		return { text: md.slice(0, 100_000), source: isPr ? "github-pr-api" : "github-issue-api" };
+	}
+
+	// repo root: metadata + README
+	if (parts.length === 2) {
+		const meta = await getJson<any>(`https://api.github.com/repos/${owner}/${repo}`, signal, ghHeaders());
+		let md = `# ${meta.full_name}\n\n${meta.description ?? ""}\n\n`;
+		md += `★ ${meta.stargazers_count} · ${meta.language ?? "?"} · updated ${(meta.updated_at ?? "").slice(0, 10)}\n`;
+		if (meta.license?.spdx_id) md += `License: ${meta.license.spdx_id}\n`;
+		if (Array.isArray(meta.topics) && meta.topics.length) md += `Tags: ${meta.topics.slice(0, 8).join(", ")}\n`;
+		const branches = ["HEAD", meta.default_branch ?? "main"];
+		for (const b of branches) {
+			try {
+				const readme = await getText(`https://raw.githubusercontent.com/${owner}/${repo}/${b}/README.md`, signal);
+				md += `\n---\n\n${readme}`;
+				break;
+			} catch {
+				/* try next branch name */
+			}
+		}
+		return { text: md.slice(0, 120_000), source: "github-api" };
+	}
+
+	return null;
+};
+
+// ------------------------------------------------------- stackoverflow
+
+function stripHtml(s: string): string {
+	return s
+		.replace(/<pre><code>([\s\S]*?)<\/code><\/pre>/g, (_, c) => `\n\`\`\`\n${c.replace(/</g, "<").replace(/>/g, ">").replace(/&/g, "&")}\n\`\`\`\n`)
+		.replace(/<code>([\s\S]*?)<\/code>/g, (_, c) => `\`${c.replace(/</g, "<").replace(/>/g, ">").replace(/&/g, "&")}\``)
+		.replace(/<(p|br|div|li|h[1-6])[^>]*>/gi, "\n")
+		.replace(/<[^>]+>/g, "")
+		.replace(/</g, "<")
+		.replace(/>/g, ">")
+		.replace(/"/g, '"')
+		.replace(/&#39;/g, "'")
+		.replace(/&/g, "&")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+const stackOverflowAdapter: Adapter = async (url, signal) => {
+	const m = url.pathname.match(/\/questions\/(\d+)/);
+	if (!m) return null;
+	const id = m[1];
+	const q = await getJson<any>(
+		`https://api.stackexchange.com/2.3/questions/${id}/answers?order=desc&sort=votes&site=stackoverflow&filter=withbody&pagesize=5`,
+		signal,
+	);
+	const qData = await getJson<any>(`https://api.stackexchange.com/2.3/questions/${id}?site=stackoverflow&filter=!9Z(-wwYGT`, signal).catch(() => null);
+	const question = qData?.items?.[0];
+	let md = question ? `# ${question.title}\n\n${stripHtml(question.body ?? "")}\n` : "";
+	const answers = (q.items ?? []) as any[];
+	if (answers.length > 0) {
+		md += `\n---\n\n## Answers\n\n` + answers
+			.map((a) => `${a.is_accepted ? "**Accepted answer**\n\n" : ""}${stripHtml(a.body ?? "")}`)
+			.join("\n\n---\n\n");
+	} else {
+		md += "\n(no answers yet)\n";
+	}
+	return { text: md.slice(0, 100_000), source: "stackexchange-api" };
+};
+
+function stripTags(s: string): string {
+	return s.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+// ----------------------------------------------------------------- hackernews
+
+const hnAdapter: Adapter = async (url, signal) => {
+	if (!/(^|\.)news\.ycombinator\.com$/.test(url.hostname)) return null;
+	const id = url.searchParams.get("id");
+	if (!id) return null;
+	const item = await getJson<any>(`https://hn.algolia.com/api/v1/items/${id}`, signal);
+	const flat = (n: any, depth: number): string => {
+		let s = "";
+		if (n.text) s += `${"  ".repeat(depth)}- ${String(n.text).replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim()}\n`;
+		for (const c of n.children ?? []) s += flat(c, depth + 1);
+		return s;
+	};
+	const md = `# ${item.title ?? "HN thread " + (item.id ?? "")}\n\n${item.points ? `${item.points} points · u/${item.author ?? "?"}\n\n` : ""}${flat(item, 0)}`;
+	return { text: md.slice(0, 100_000), source: "hn-algolia" };
+};
+
+// ------------------------------------------------------------------ reddit
+
+const redditAdapter: Adapter = async (url, signal) => {
+	if (!/(^|\.)reddit\.com$/.test(url.hostname) || !url.pathname.includes("/comments/")) return null;
+	const data = (await getJson<any>(url.protocol + "//" + url.host + url.pathname.replace(/\/$/, "") + ".json?limit=30", signal)) as any;
+	const post = Array.isArray(data) ? data[0]?.data?.children?.[0]?.data : null;
+	if (!post) return null;
+	let md = `# ${post.title}\n\nr/${post.subreddit} · ↑${post.ups} · u/${post.author}\n\n${post.selftext ?? ""}\n`;
+	const comments = Array.isArray(data) ? data[1]?.data?.children ?? [] : [];
+	const flat = (children: any[], depth = 0): string => {
+		let s = "";
+		for (const c of children) {
+			const d = c.data;
+			if (!d || d.kind === "more") continue;
+			s += `${"  ".repeat(depth)}- **u/${d.author}** (↑${d.ups}): ${String(d.body ?? "").replace(/\n+/g, " ").slice(0, 500)}\n`;
+			if (d.replies?.data?.children) s += flat(d.replies.data.children, depth + 1);
+		}
+		return s;
+	};
+	md += `\n## Top comments\n\n` + flat(comments);
+	return { text: md.slice(0, 80_000), source: "reddit-json" };
+};
+
+// ------------------------------------------------------------- wikipedia
+
+const wikipediaAdapter: Adapter = async (url, signal) => {
+	if (!/(^|\.)wikipedia\.org$/.test(url.hostname)) return null;
+	const m = url.pathname.match(/^\/wiki\/([^/:#]+)$/);
+	if (!m) return null;
+	const title = decodeURIComponent(m[1]);
+	const summary = await getJson<any>(`https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(title)}`, signal).catch(() => null);
+	const apiHost = url.hostname.startsWith("en.") ? url.hostname : "en.wikipedia.org";
+	const raw = await getText(`https://${apiHost}/api/rest_v1/page/html/${encodeURIComponent(title)}`, signal).catch(() => "");
+	if (!raw) return null;
+	// reuse the extractor's markdown conversion
+	const { htmlToMarkdown } = await import("./extract.ts");
+	const converted = htmlToMarkdown(raw, url.href, 200_000);
+	let md = converted.text;
+	if (summary?.extract && !md.includes(summary.extract.slice(0, 80))) {
+		md = `${summary.extract}\n\n${md}`;
+	}
+	return { text: md.slice(0, 200_000), source: "wikipedia-rest" };
+};
+
+// ------------------------------------------------------------------ router
+
+const ADAPTERS: Array<[RegExp, Adapter]> = [
+	[/^github\.com$/, githubAdapter],
+	[/^(www\.)?stackoverflow\.com$/, stackOverflowAdapter],
+	[/^(www\.)?reddit\.com$/, redditAdapter],
+	[/^news\.ycombinator\.com$/, hnAdapter],
+	[/^(en\.)?wikipedia\.org$/, wikipediaAdapter],
+];
+
+/**
+ * Try site adapters for a URL. Returns null when no adapter matches or all
+ * fail — caller falls back to the generic HTML pipeline.
+ */
+export async function trySiteAdapter(url: string, signal?: AbortSignal): Promise<AdapterResult | null> {
+	let u: URL;
+	try {
+		u = new URL(url);
+	} catch {
+		return null;
+	}
+	if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+	for (const [hostRe, adapter] of ADAPTERS) {
+		if (!hostRe.test(u.hostname)) continue;
+		try {
+			const r = await adapter(u, signal);
+			if (r && r.text.length > 80) return r;
+		} catch {
+			return null; // adapter exists but failed — generic path is more honest than an error
+		}
+	}
+	return null;
+}

package/lib/apis.ts

@@ -0,0 +1,221 @@
+/**
+ * Specialized search APIs — all free, no API keys required.
+ *   - Stack Exchange (Stack Overflow): 300 req/day per IP, no key
+ *   - Wikipedia (MediaWiki OpenSearch): unlimited reasonable use
+ *   - npm registry: unlimited, no key
+ *   - GitHub search: 10 req/min unauthenticated
+ *   - Hacker News (Algolia): unlimited, no key
+ */
+import { createDiskBackedCache } from "./cache.ts";
+
+const UA =
+	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+const TIMEOUT_MS = 15_000;
+const CACHE = createDiskBackedCache({ name: "apis", maxEntries: 256, ttlMs: 10 * 60 * 1000 });
+
+export interface ApiResult {
+	title: string;
+	url: string;
+	snippet: string;
+	meta?: string;
+}
+
+export async function getJson<T>(url: string, signal?: AbortSignal, headers?: Record<string, string>): Promise<T> {
+	const timeout = AbortSignal.timeout(TIMEOUT_MS);
+	const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+	const res = await fetch(url, {
+		headers: { "User-Agent": UA, Accept: "application/json", ...headers },
+		signal: combined,
+	});
+	if (!res.ok) throw new Error(`HTTP ${res.status} from ${new URL(url).host}`);
+	return (await res.json()) as T;
+}
+
+// ------------------------------------------------------------- stackoverflow
+
+interface SeItem {
+	title: string;
+	link: string;
+	score: number;
+	answer_count: number;
+	is_answered: boolean;
+	is_accepted?: boolean;
+	tags?: string[];
+	excerpt?: string;
+	creation_date: number;
+}
+
+export async function searchStackOverflow(
+	query: string,
+	max: number,
+	signal?: AbortSignal,
+): Promise<ApiResult[]> {
+	const key = `so:${max}:${query}`;
+	const cached = CACHE.get(key);
+	if (cached) return cached as ApiResult[];
+	const u = new URL("https://api.stackexchange.com/2.3/search/advanced");
+	u.searchParams.set("order", "desc");
+	u.searchParams.set("sort", "relevance");
+	u.searchParams.set("q", query);
+	u.searchParams.set("site", "stackoverflow");
+	u.searchParams.set("pagesize", String(Math.min(Math.max(max, 1), 30)));
+	u.searchParams.set("filter", "!nNPvSNdWme"); // includes excerpt
+	const data = await getJson<{ items?: SeItem[]; quota_remaining?: number; error_message?: string }>(
+		u.toString(),
+		signal,
+	);
+	if (data.error_message) throw new Error(`stackexchange: ${data.error_message}`);
+	const results = (data.items ?? []).map((it) => ({
+		title: it.title.replace(/"/g, '"').replace(/&#39;/g, "'").replace(/&/g, "&"),
+		url: `https://stackoverflow.com/questions/${it.question_id}`,
+		snippet: (it.excerpt ?? "").trim(),
+		meta: `▲${it.score} · ${it.answer_count} answers${it.is_accepted ? " · ✓accepted" : ""} · [${(it.tags ?? []).slice(0, 4).join(", ")}]`,
+	}));
+	CACHE.set(key, results);
+	return results;
+}
+
+// ---------------------------------------------------------------- wikipedia
+
+interface WikiSearchItem {
+	title: string;
+	snippet: string; // contains <span class="searchmatch"> html
+	pageid: number;
+}
+
+export async function searchWikipedia(
+	query: string,
+	max: number,
+	signal?: AbortSignal,
+): Promise<ApiResult[]> {
+	const key = `wiki:${max}:${query}`;
+	const cached = CACHE.get(key);
+	if (cached) return cached as ApiResult[];
+	const u = new URL("https://en.wikipedia.org/w/api.php");
+	u.searchParams.set("action", "query");
+	u.searchParams.set("list", "search");
+	u.searchParams.set("srsearch", query);
+	u.searchParams.set("srlimit", String(Math.min(Math.max(max, 1), 30)));
+	u.searchParams.set("format", "json");
+	const data = await getJson<{ query?: { search?: WikiSearchItem[] } }>(u.toString(), signal);
+	const results = (data.query?.search ?? []).map((it) => ({
+		title: it.title,
+		url: `https://en.wikipedia.org/wiki/${encodeURIComponent(it.title.replace(/ /g, "_"))}`,
+		snippet: it.snippet.replace(/<[^>]+>/g, "").trim(),
+		meta: "wikipedia",
+	}));
+	CACHE.set(key, results);
+	return results;
+}
+
+// ---------------------------------------------------------------------- npm
+
+interface NpmObject {
+	package: {
+		name: string;
+		version: string;
+		description?: string;
+		links?: { npm?: string };
+		publisher?: { username?: string };
+		date?: string;
+	};
+	score?: { final: number; detail: { popularity: number; quality: number; maintenance: number } };
+}
+
+export async function searchNpm(query: string, max: number, signal?: AbortSignal): Promise<ApiResult[]> {
+	const key = `npm:${max}:${query}`;
+	const cached = CACHE.get(key);
+	if (cached) return cached as ApiResult[];
+	const u = new URL("https://registry.npmjs.org/-/v1/search");
+	u.searchParams.set("text", query);
+	u.searchParams.set("size", String(Math.min(Math.max(max, 1), 20)));
+	const data = await getJson<{ objects?: NpmObject[] }>(u.toString(), signal);
+	const results = (data.objects ?? []).map((o) => ({
+		title: `${o.package.name} v${o.package.version}`,
+		url: o.package.links?.npm ?? `https://www.npmjs.com/package/${o.package.name}`,
+		snippet: o.package.description ?? "",
+		meta: `⭐quality ${(100 * (o.score?.detail.quality ?? 0)).toFixed(0)} · pop ${(100 * (o.score?.detail.popularity ?? 0)).toFixed(0)}`,
+	}));
+	CACHE.set(key, results);
+	return results;
+}
+
+// -------------------------------------------------------------------- github
+
+interface GhRepo {
+	full_name: string;
+	html_url: string;
+	description: string | null;
+	stargazers_count: number;
+	language: string | null;
+	updated_at: string;
+}
+
+interface GhSearchResponse {
+	items?: GhRepo[];
+	message?: string;
+}
+
+export async function searchGithubRepos(
+	query: string,
+	max: number,
+	signal?: AbortSignal,
+	token?: string,
+): Promise<ApiResult[]> {
+	const key = `gh:${max}:${query}`;
+	const cached = CACHE.get(key);
+	if (cached) return cached as ApiResult[];
+	const u = new URL("https://api.github.com/search/repositories");
+	u.searchParams.set("q", query);
+	u.searchParams.set("per_page", String(Math.min(Math.max(max, 1), 30)));
+	u.searchParams.set("sort", "best-match");
+	const data = await getJson<GhSearchResponse>(u.toString(), signal, token ? { Authorization: `Bearer ${token}` } : {});
+	if (data.message) throw new Error(`github: ${data.message}`);
+	const results = (data.items ?? []).map((r) => ({
+		title: r.full_name,
+		url: r.html_url,
+		snippet: r.description ?? "",
+		meta: `★${r.stargazers_count} · ${r.language ?? "?"} · updated ${new Date(r.updated_at).toISOString().slice(0, 10)}`,
+	}));
+	CACHE.set(key, results);
+	return results;
+}
+
+// ---------------------------------------------------------------- hackernews
+
+interface HnHit {
+	title: string | null;
+	url: string | null;
+	objectID: string;
+	points: number | null;
+	num_comments: number | null;
+	story_text?: string | null;
+	comment_text?: string | null;
+	created_at: string;
+}
+
+export async function searchHackerNews(
+	query: string,
+	max: number,
+	signal?: AbortSignal,
+): Promise<ApiResult[]> {
+	const key = `hn:${max}:${query}`;
+	const cached = CACHE.get(key);
+	if (cached) return cached as ApiResult[];
+	const u = new URL("https://hn.algolia.com/api/v1/search");
+	u.searchParams.set("query", query);
+	u.searchParams.set("hitsPerPage", String(Math.min(Math.max(max, 1), 30)));
+	const data = await getJson<{ hits?: HnHit[] }>(u.toString(), signal);
+	const results = (data.hits ?? [])
+		.filter((h) => h.title || h.story_title)
+		.map((h) => ({
+			title: h.title ?? h.story_title ?? "(untitled)",
+			url:
+				h.url ??
+				(h.story_text ? `https://news.ycombinator.com/item?id=${h.objectID}` : `https://news.ycombinator.com/item?id=${h.objectID}`),
+			snippet: (h.story_text ? h.story_text.replace(/<[^>]+>/g, "").slice(0, 200) : "").trim(),
+			meta: `▲${h.points ?? 0} · ${h.num_comments ?? 0} comments · ${h.created_at.slice(0, 10)}`,
+		}));
+	CACHE.set(key, results);
+	return results;
+}

package/lib/cache.ts

@@ -0,0 +1,160 @@
+/**
+ * Generic TTL + LRU cache used across engines, APIs and the fetcher.
+ *
+ * `createDiskBackedCache` adds a JSON file layer under `~/.pi/agent/cache/webfind`:
+ * memory stays the hot path; disk survives restarts (search pages, fetched
+ * article text). Writes are debounced and flushed on a timer + process exit.
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export function createTtlCache(maxEntries: number, ttlMs: number) {
+	const map = new Map<string, { at: number; value: unknown }>();
+	return {
+		get(key: string): unknown | null {
+			const hit = map.get(key);
+			if (!hit) return null;
+			if (Date.now() - hit.at > ttlMs) {
+				map.delete(key);
+				return null;
+			}
+			// LRU refresh
+			map.delete(key);
+			map.set(key, hit);
+			return hit.value;
+		},
+		set(key: string, value: unknown) {
+			if (map.size >= maxEntries) {
+				const oldest = map.keys().next().value;
+				if (oldest) map.delete(oldest);
+			}
+			map.set(key, { at: Date.now(), value });
+		},
+	};
+}
+
+const DISK_LIMIT_BYTES = 8 * 1024 * 1024; // keep each snapshot small
+
+export interface DiskBackedCache {
+	get(key: string): unknown | null;
+	set(key: string, value: unknown): void;
+	/** Force a synchronous write (used on process exit). */
+	flushSync(): void;
+}
+
+/**
+ * Memory-first cache with a JSON disk snapshot. On first use, loads the disk
+ * file (pruning expired entries). `set` updates memory and schedules a
+ * debounced flush; process exit flushes synchronously.
+ */
+export function createDiskBackedCache(opts: {
+	name: string; // file name without extension
+	maxEntries: number;
+	ttlMs: number;
+	flushMs?: number;
+}): DiskBackedCache {
+	const map = new Map<string, { at: number; value: unknown }>();
+	const dir = join(homedir(), ".pi", "agent", "cache", "webfind");
+	const file = join(dir, `${opts.name}.json`);
+	let loaded = false;
+	let dirty = false;
+	let maxAt = 0;
+
+	const load = () => {
+		if (loaded) return;
+		loaded = true;
+		try {
+			if (!existsSync(file)) return;
+			const entries = JSON.parse(readFileSync(file, "utf8")) as Array<[string, { at: number; value: unknown }]>;
+			const now = Date.now();
+			for (const [k, v] of entries) {
+				if (typeof v?.at === "number" && typeof k === "string" && now - v.at <= opts.ttlMs) {
+					map.set(k, v);
+					if (v.at > maxAt) maxAt = v.at;
+				}
+			}
+		} catch {
+			// corrupt snapshot — ignore, start fresh
+		}
+	};
+
+	const evict = () => {
+		while (map.size >= opts.maxEntries) {
+			// drop the oldest entry
+			let oldestKey: string | null = null;
+			let oldestAt = Infinity;
+			for (const [k, v] of map) {
+				if (v.at < oldestAt) {
+					oldestAt = v.at;
+					oldestKey = k;
+				}
+			}
+			if (!oldestKey) break;
+			map.delete(oldestKey);
+		}
+	};
+
+	const flush = () => {
+		if (!dirty) return;
+		dirty = false;
+		try {
+			mkdirSync(dir, { recursive: true });
+			const entries = [...map.entries()];
+			const body = JSON.stringify(entries);
+			if (body.length > DISK_LIMIT_BYTES) {
+				// over budget: keep the newest half
+				entries.sort((a, b) => b[1].at - a[1].at);
+				writeFileSync(file, JSON.stringify(entries.slice(0, Math.ceil(entries.length / 2))));
+			} else {
+				writeFileSync(file, body);
+			}
+		} catch {
+			// disk full/readonly — cache silently degrades to memory-only
+		}
+	};
+
+	// debounced background flush
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	const schedule = () => {
+		if (timer) return;
+		timer = setTimeout(() => {
+			timer = null;
+			flush();
+		}, opts.flushMs ?? 3_000);
+		if (typeof timer === "object" && "unref" in (timer as any)) (timer as any).unref?.();
+	};
+
+	// flush on exit (best effort)
+	process.on("exit", () => flush());
+	try {
+		process.on("SIGINT", () => {
+			flush();
+		});
+	} catch {
+		/* not always available */
+	}
+
+	return {
+		get(key: string) {
+			load();
+			const hit = map.get(key);
+			if (!hit) return null;
+			if (Date.now() - hit.at > opts.ttlMs) {
+				map.delete(key);
+				return null;
+			}
+			return hit.value;
+		},
+		set(key: string, value: unknown) {
+			load();
+			evict();
+			const at = Math.max(Date.now(), maxAt + 1); // strictly increasing → stable eviction order
+			maxAt = at;
+			map.set(key, { at, value });
+			dirty = true;
+			schedule();
+		},
+		flushSync: flush,
+	};
+}