@sayknow-cli/coding-agent 0.3.1 → 0.3.4

package/src/tools/fetch.ts

@@ -17,7 +17,7 @@ import { CachedOutputBlock } from "../tui/output-block";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { ensureTool } from "../utils/tools-manager";
 import { INSANE_NOTES, tryInsaneFetch } from "../web/insane/bridge";
-import { validatePublicHttpUrlForInsane } from "../web/insane/url-guard";
+import { validatePublicHttpUrl, validatePublicHttpUrlForInsane } from "../web/insane/url-guard";
 import { extractWithParallel, findParallelApiKey, getParallelExtractContent } from "../web/parallel";
 import { specialHandlers } from "../web/scrapers";
 import type { RenderResult } from "../web/scrapers/types";
@@ -789,6 +789,21 @@ async function renderUrl(
 
 	// Step 0: Normalize URL (ensure scheme for special handlers)
 	url = normalizeUrl(url);
+	const publicUrl = await validatePublicHttpUrl(url);
+	if (!publicUrl.ok) {
+		notes.push(`Blocked URL fetch: target URL is not public HTTP(S): ${publicUrl.reason}`);
+		return {
+			url,
+			finalUrl: url,
+			contentType: "unknown",
+			method: "failed",
+			content: "",
+			fetchedAt,
+			truncated: false,
+			notes,
+		};
+	}
+	url = publicUrl.url.toString();
 
 	// Step 1: Try special handlers for known sites (unless raw mode)
 	if (!raw) {
@@ -802,7 +817,8 @@ async function renderUrl(
 		throw new ToolAbortError();
 	}
 	if (!response.ok) {
-		const failureNote = response.status ? `Failed to fetch URL (HTTP ${response.status})` : "Failed to fetch URL";
+		const failureNote =
+			response.error ?? (response.status ? `Failed to fetch URL (HTTP ${response.status})` : "Failed to fetch URL");
 		notes.push(failureNote);
 		const insane = await tryInsaneFallback({
 			url,

package/src/tools/index.ts

@@ -1,5 +1,5 @@
 import type { AgentTelemetryConfig, AgentTool } from "@sayknow-cli/agent-core";
-import type { Model, ToolChoice } from "@sayknow-cli/ai";
+import type { Model, ServiceTier, ToolChoice } from "@sayknow-cli/ai";
 import { $env, $flag, logger } from "@sayknow-cli/utils";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
@@ -38,12 +38,11 @@ import { BrowserTool } from "./browser";
 import { CalculatorTool } from "./calculator";
 import { type CheckpointState, CheckpointTool, RewindTool } from "./checkpoint";
 import { ComputerTool, isComputerCallable, isComputerLoadablePlatform } from "./computer";
-import { CronCreateTool, CronDeleteTool, CronListTool } from "./cron";
+import { CronTool } from "./cron";
 import { DebugTool } from "./debug";
 import { EvalTool } from "./eval";
 import { FindTool } from "./find";
 import { GithubTool } from "./gh";
-import { InspectImageTool } from "./inspect-image";
 import { IrcTool } from "./irc";
 import { JobTool } from "./job";
 import { MonitorTool } from "./monitor";
@@ -83,7 +82,6 @@ export * from "./eval";
 export * from "./find";
 export * from "./gh";
 export * from "./image-gen";
-export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
 export * from "./monitor";
@@ -222,6 +220,8 @@ export interface ToolSession {
 	agentOutputManager?: AgentOutputManager;
 	/** Settings instance for passing to subagents */
 	settings: Settings;
+	/** Live service-tier intent of the parent session, inherited by `inherit` subagents. */
+	serviceTier?: ServiceTier;
 	/** Plan mode state (if active) */
 	getPlanModeState?: () => PlanModeState | undefined;
 	/** Goal mode state (if active or paused) */
@@ -387,7 +387,6 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	find: s => new FindTool(s),
 	search: s => new SearchTool(s),
 	lsp: LspTool.createIf,
-	inspect_image: s => new InspectImageTool(s),
 	browser: s => new BrowserTool(s),
 	...(isComputerLoadablePlatform() ? { computer: ComputerTool.createIf } : {}),
 	checkpoint: CheckpointTool.createIf,
@@ -396,9 +395,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	subagent: s => new SubagentTool(s),
 	job: JobTool.createIf,
 	monitor: MonitorTool.createIf,
-	CronCreate: CronCreateTool.createIf,
-	CronList: CronListTool.createIf,
-	CronDelete: CronDeleteTool.createIf,
+	cron: CronTool.createIf,
 	recipe: RecipeTool.createIf,
 	irc: IrcTool.createIf,
 	todo_write: s => new TodoWriteTool(s),
@@ -558,7 +555,6 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "ast_grep") return session.settings.get("astGrep.enabled");
 		if (name === "ast_edit") return session.settings.get("astEdit.enabled");
 		if (name === "render_mermaid") return session.settings.get("renderMermaid.enabled");
-		if (name === "inspect_image") return session.settings.get("inspect_image.enabled");
 		if (name === "web_search") return session.settings.get("web_search.enabled");
 		// search_tool_bm25 is allowed when either legacy mcp.discoveryMode or new tools.discoveryMode is active.
 		if (name === "search_tool_bm25") return discoveryActive;

package/src/tools/read.ts

@@ -670,7 +670,6 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 
 	readonly #autoResizeImages: boolean;
 	readonly #defaultLimit: number;
-	readonly #inspectImageEnabled: boolean;
 
 	constructor(private readonly session: ToolSession) {
 		const displayMode = resolveFileDisplayMode(session);
@@ -679,7 +678,6 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			1,
 			Math.min(session.settings.get("read.defaultLimit") ?? DEFAULT_MAX_LINES, DEFAULT_MAX_LINES),
 		);
-		this.#inspectImageEnabled = session.settings.get("inspect_image.enabled");
 		this.description = prompt.render(readDescription, {
 			DEFAULT_LIMIT: String(this.#defaultLimit),
 			DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
@@ -1572,62 +1570,34 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			| undefined;
 
 		if (mimeType) {
-			if (this.#inspectImageEnabled) {
-				const metadata = imageMetadata;
-				const outputMime = metadata?.mimeType ?? mimeType;
-				const outputBytes = fileSize;
-				const metadataLines = [
-					"Image metadata:",
-					`- MIME: ${outputMime}`,
-					`- Bytes: ${outputBytes} (${formatBytes(outputBytes)})`,
-					metadata?.width !== undefined && metadata.height !== undefined
-						? `- Dimensions: ${metadata.width}x${metadata.height}`
-						: "- Dimensions: unknown",
-					metadata?.channels !== undefined ? `- Channels: ${metadata.channels}` : "- Channels: unknown",
-					metadata?.hasAlpha === true
-						? "- Alpha: yes"
-						: metadata?.hasAlpha === false
-							? "- Alpha: no"
-							: "- Alpha: unknown",
-					"",
-					`If you want to analyze the image, call inspect_image with path="${formatPathRelativeToCwd(
-						absolutePath,
-						this.session.cwd,
-					)}" and a question describing what to inspect and the desired output format.`,
+			if (fileSize > MAX_IMAGE_SIZE) {
+				const sizeStr = formatBytes(fileSize);
+				const maxStr = formatBytes(MAX_IMAGE_SIZE);
+				throw new ToolError(`Image file too large: ${sizeStr} exceeds ${maxStr} limit.`);
+			}
+			try {
+				const imageInput = await loadImageInput({
+					path: readPath,
+					cwd: this.session.cwd,
+					autoResize: this.#autoResizeImages,
+					maxBytes: MAX_IMAGE_SIZE,
+					resolvedPath: absolutePath,
+					detectedMimeType: mimeType,
+				});
+				if (!imageInput) {
+					throw new ToolError(`Read image file [${mimeType}] failed: unsupported image format.`);
+				}
+				content = [
+					{ type: "text", text: imageInput.textNote },
+					{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
 				];
-				content = [{ type: "text", text: metadataLines.join("\n") }];
 				details = {};
-				sourcePath = absolutePath;
-			} else {
-				if (fileSize > MAX_IMAGE_SIZE) {
-					const sizeStr = formatBytes(fileSize);
-					const maxStr = formatBytes(MAX_IMAGE_SIZE);
-					throw new ToolError(`Image file too large: ${sizeStr} exceeds ${maxStr} limit.`);
-				}
-				try {
-					const imageInput = await loadImageInput({
-						path: readPath,
-						cwd: this.session.cwd,
-						autoResize: this.#autoResizeImages,
-						maxBytes: MAX_IMAGE_SIZE,
-						resolvedPath: absolutePath,
-						detectedMimeType: mimeType,
-					});
-					if (!imageInput) {
-						throw new ToolError(`Read image file [${mimeType}] failed: unsupported image format.`);
-					}
-					content = [
-						{ type: "text", text: imageInput.textNote },
-						{ type: "image", data: imageInput.data, mimeType: imageInput.mimeType },
-					];
-					details = {};
-					sourcePath = imageInput.resolvedPath;
-				} catch (error) {
-					if (error instanceof ImageInputTooLargeError) {
-						throw new ToolError(error.message);
-					}
-					throw error;
+				sourcePath = imageInput.resolvedPath;
+			} catch (error) {
+				if (error instanceof ImageInputTooLargeError) {
+					throw new ToolError(error.message);
 				}
+				throw error;
 			}
 		} else if (isNotebookPath(absolutePath) && !isRawSelector(parsed)) {
 			const notebookText = await readEditableNotebookText(absolutePath, localReadPath);

package/src/tools/renderers.ts

@@ -22,7 +22,6 @@ import { debugToolRenderer } from "./debug";
 import { evalToolRenderer } from "./eval";
 import { findToolRenderer } from "./find";
 import { githubToolRenderer } from "./gh-renderer";
-import { inspectImageToolRenderer } from "./inspect-image-renderer";
 import { jobToolRenderer } from "./job";
 import { readToolRenderer } from "./read";
 import { recipeToolRenderer } from "./recipe/render";
@@ -63,7 +62,6 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	find: findToolRenderer as ToolRenderer,
 	search: searchToolRenderer as ToolRenderer,
 	lsp: lspToolRenderer as ToolRenderer,
-	inspect_image: inspectImageToolRenderer as ToolRenderer,
 	read: readToolRenderer as ToolRenderer,
 	job: jobToolRenderer as ToolRenderer,
 	resolve: resolveToolRenderer as ToolRenderer,

package/src/tools/resource-gc.ts

@@ -0,0 +1,291 @@
+import { logger } from "@sayknow-cli/utils";
+import type { Settings } from "../config/settings";
+import { listTabsForGc, releaseTabIfGcEligible, type TabGcSnapshot } from "./browser/tab-supervisor";
+import { cleanupStaleScreenshotFallbackDirs, hasCreatedScreenshotFallbackDir } from "./computer-gc";
+
+/**
+ * Mandatory, session-aware resource garbage collector.
+ *
+ * A single process-wide, reference-counted, unref'd, non-overlapping interval sweeps:
+ *  - browser tabs (the heavyweight resource: one worker thread per tab + Chrome child
+ *    processes) via an idle sweep and an opportunistic RSS-pressure sweep, and
+ *  - stale computer-use screenshot fallback directories on disk (lazy-armed + throttled).
+ *
+ * Eviction targets ONLY alive, non-in-flight, SKC-managed headless/spawned tabs owned by a
+ * registered session; connected/real-Chrome/held/in-flight tabs and ownerless tabs are never
+ * touched. RSS is the SKC parent-process RSS only (`process.memoryUsage().rss`); pressure
+ * eviction is best-effort and never force-evicts.
+ */
+
+const DEFAULT_SWEEP_INTERVAL_MS = 30_000;
+const BYTES_PER_MB = 1024 * 1024;
+
+export interface BrowserGcPolicy {
+	enabled: boolean;
+	idleMs: number;
+	rssLimitBytes: number;
+}
+
+export interface ComputerGcPolicy {
+	enabled: boolean;
+	staleMs: number;
+	scanIntervalMs: number;
+}
+
+export function resolveBrowserGcPolicy(settings: Settings): BrowserGcPolicy {
+	return {
+		enabled: settings.get("browser.gc.enabled"),
+		idleMs: settings.get("browser.gc.idleMs"),
+		rssLimitBytes: settings.get("browser.gc.rssLimitMb") * BYTES_PER_MB,
+	};
+}
+
+export function resolveComputerGcPolicy(settings: Settings): ComputerGcPolicy {
+	return {
+		enabled: settings.get("computer.screenshotGc.enabled"),
+		staleMs: settings.get("computer.screenshotGc.staleMs"),
+		scanIntervalMs: settings.get("computer.screenshotGc.scanIntervalMs"),
+	};
+}
+
+export function resolveSweepIntervalMs(settings: Settings): number {
+	return settings.get("resourceGc.sweepIntervalMs");
+}
+
+/** Injectable seams so the controller is fully testable without real browsers/filesystem/RSS. */
+export interface ResourceGcDeps {
+	now: () => number;
+	rssBytes: () => number;
+	logWarn: (msg: string, meta?: Record<string, unknown>) => void;
+	listTabs: () => TabGcSnapshot[];
+	releaseTab: (name: string, policy: { now: () => number; idleMs: number }) => Promise<boolean>;
+	cleanupScreenshots: (opts: { now: () => number; staleMs: number }) => Promise<{ scanned: number; removed: number }>;
+	screenshotArmed: () => boolean;
+}
+
+const defaultDeps: ResourceGcDeps = {
+	now: () => Date.now(),
+	rssBytes: () => process.memoryUsage().rss,
+	logWarn: (msg, meta) => logger.warn(msg, meta),
+	listTabs: () => listTabsForGc(),
+	releaseTab: (name, policy) => releaseTabIfGcEligible(name, policy),
+	cleanupScreenshots: opts => cleanupStaleScreenshotFallbackDirs(opts),
+	screenshotArmed: () => hasCreatedScreenshotFallbackDir(),
+};
+
+// ── Controller state (process-global; tabs/browsers are module-global too) ──────────────────
+const activeSessions = new Map<string, Settings>();
+let timer: ReturnType<typeof setTimeout> | null = null;
+let stopped = false;
+// Bumped on every stop so an in-flight tick from a previous schedule cannot reschedule after a
+// stop+re-register and leak a duplicate timer.
+let timerGeneration = 0;
+let inProgress = false;
+let rssWarningActive = false;
+let lastScreenshotScanAt = 0;
+let deps: ResourceGcDeps = defaultDeps;
+
+export interface ResourceGcRegistration {
+	sessionId: string;
+	settings: Settings;
+}
+
+/**
+ * Register a session with the resource GC. Starts the single shared timer on the first
+ * registration. Returns an idempotent unregister function; the timer stops only when the last
+ * session unregisters.
+ */
+export function registerResourceGcSession(reg: ResourceGcRegistration): () => void {
+	activeSessions.set(reg.sessionId, reg.settings);
+	ensureTimerStarted();
+	let unregistered = false;
+	return () => {
+		if (unregistered) return;
+		unregistered = true;
+		activeSessions.delete(reg.sessionId);
+		if (activeSessions.size === 0) stopTimer();
+	};
+}
+
+function currentSweepIntervalMs(): number {
+	let min = Number.POSITIVE_INFINITY;
+	for (const settings of activeSessions.values()) min = Math.min(min, resolveSweepIntervalMs(settings));
+	return Number.isFinite(min) ? min : DEFAULT_SWEEP_INTERVAL_MS;
+}
+
+function ensureTimerStarted(): void {
+	if (timer) return;
+	stopped = false;
+	scheduleNextSweep();
+}
+
+// Recursive setTimeout (not setInterval) so the cadence is recomputed every cycle and later
+// session register/unregister changes to resourceGc.sweepIntervalMs are honored live.
+function scheduleNextSweep(): void {
+	if (stopped || activeSessions.size === 0) {
+		timer = null;
+		return;
+	}
+	const generation = timerGeneration;
+	timer = setTimeout(() => {
+		void tickAndReschedule(generation);
+	}, currentSweepIntervalMs());
+	timer.unref?.();
+}
+
+async function tickAndReschedule(generation: number): Promise<void> {
+	await runTick();
+	// A stop (and possible re-register) happened during the tick: a newer cycle owns the timer now.
+	if (generation !== timerGeneration) return;
+	scheduleNextSweep();
+}
+
+function stopTimer(): void {
+	stopped = true;
+	timerGeneration++;
+	if (timer) {
+		clearTimeout(timer);
+		timer = null;
+	}
+}
+
+async function runTick(): Promise<void> {
+	if (inProgress) return;
+	inProgress = true;
+	try {
+		await sweepOnce(deps);
+	} catch (err) {
+		logger.debug("resource GC sweep failed", { error: (err as Error).message });
+	} finally {
+		inProgress = false;
+	}
+}
+
+export async function sweepOnce(d: ResourceGcDeps = deps): Promise<void> {
+	if (activeSessions.size === 0) return;
+	await sweepBrowserTabs(d);
+	await sweepScreenshots(d);
+}
+
+function ownerBrowserPolicy(snapshot: TabGcSnapshot): BrowserGcPolicy | null {
+	if (!snapshot.ownerId) return null;
+	const settings = activeSessions.get(snapshot.ownerId);
+	if (!settings) return null;
+	return resolveBrowserGcPolicy(settings);
+}
+
+/** Coarse, ordering-only eligibility; the live recheck in releaseTabIfGcEligible is authoritative. */
+function isCoarselyEligible(snapshot: TabGcSnapshot): boolean {
+	return (
+		snapshot.state === "alive" &&
+		snapshot.pendingCount === 0 &&
+		(snapshot.kindTag === "headless" || snapshot.kindTag === "spawned")
+	);
+}
+
+/** Collect idle, non-in-flight, SKC-managed, owned-and-enabled tabs, sorted LRU (oldest first). */
+function collectIdleCandidates(d: ResourceGcDeps): Array<{ snapshot: TabGcSnapshot; policy: BrowserGcPolicy }> {
+	const candidates: Array<{ snapshot: TabGcSnapshot; policy: BrowserGcPolicy }> = [];
+	for (const snapshot of d.listTabs()) {
+		if (!isCoarselyEligible(snapshot)) continue;
+		const policy = ownerBrowserPolicy(snapshot);
+		if (!policy?.enabled) continue;
+		if (d.now() - snapshot.lastUsedAt <= policy.idleMs) continue;
+		candidates.push({ snapshot, policy });
+	}
+	candidates.sort((a, b) => a.snapshot.lastUsedAt - b.snapshot.lastUsedAt);
+	return candidates;
+}
+
+async function sweepBrowserTabs(d: ResourceGcDeps): Promise<void> {
+	// Reclamation honors IR-1 strictly: ONLY idle, non-in-flight, SKC-managed, owned tabs are ever
+	// evicted. RSS pressure never relaxes that boundary — it only drives the warning below.
+	for (const { snapshot, policy } of collectIdleCandidates(d)) {
+		await d.releaseTab(snapshot.name, { now: d.now, idleMs: policy.idleMs });
+	}
+	evaluateRssPressureWarning(d);
+}
+
+/** Owners whose own RSS limit is exceeded by the single shared parent-process RSS sample. */
+function pressuredOwnerIds(d: ResourceGcDeps): Set<string> {
+	const rss = d.rssBytes();
+	const owners = new Set<string>();
+	for (const [sessionId, settings] of activeSessions) {
+		const policy = resolveBrowserGcPolicy(settings);
+		if (policy.enabled && rss > policy.rssLimitBytes) owners.add(sessionId);
+	}
+	return owners;
+}
+
+/**
+ * RSS pressure is a best-effort warning signal only. Because eviction is always idle-gated
+ * (IR-1), when parent-process RSS stays over an enabled owner's limit and no idle, unheld tab
+ * remains to reclaim for a pressured owner, we warn exactly once per continuous episode and
+ * never force-evict. The warning episode resets when RSS recovers or a reclaimable tab appears.
+ */
+function evaluateRssPressureWarning(d: ResourceGcDeps): void {
+	const pressured = pressuredOwnerIds(d);
+	if (pressured.size === 0) {
+		rssWarningActive = false;
+		return;
+	}
+	const reclaimableRemains = collectIdleCandidates(d).some(
+		c => c.snapshot.ownerId !== undefined && pressured.has(c.snapshot.ownerId),
+	);
+	if (reclaimableRemains) {
+		rssWarningActive = false;
+		return;
+	}
+	if (!rssWarningActive) {
+		rssWarningActive = true;
+		d.logWarn("Browser GC: RSS over limit but no safe (idle, unheld) browser tabs are evictable", {
+			rssBytes: d.rssBytes(),
+		});
+	}
+}
+
+async function sweepScreenshots(d: ResourceGcDeps): Promise<void> {
+	if (!d.screenshotArmed()) return;
+
+	let staleMs: number | null = null;
+	let scanIntervalMs = Number.POSITIVE_INFINITY;
+	for (const settings of activeSessions.values()) {
+		const policy = resolveComputerGcPolicy(settings);
+		if (!policy.enabled) continue;
+		staleMs = staleMs === null ? policy.staleMs : Math.min(staleMs, policy.staleMs);
+		scanIntervalMs = Math.min(scanIntervalMs, policy.scanIntervalMs);
+	}
+	if (staleMs === null) return; // no session has screenshot GC enabled
+
+	const now = d.now();
+	if (now - lastScreenshotScanAt < scanIntervalMs) return;
+	lastScreenshotScanAt = now;
+	await d.cleanupScreenshots({ now: d.now, staleMs });
+}
+
+// ── Test-only seams ─────────────────────────────────────────────────────────────────────────
+export function __setResourceGcDepsForTest(overrides: Partial<ResourceGcDeps>): void {
+	deps = { ...defaultDeps, ...overrides };
+}
+
+export async function __runResourceGcTickForTest(): Promise<void> {
+	await runTick();
+}
+
+export function __getResourceGcStateForTest(): {
+	timerActive: boolean;
+	sessionCount: number;
+	rssWarningActive: boolean;
+	inProgress: boolean;
+} {
+	return { timerActive: timer !== null, sessionCount: activeSessions.size, rssWarningActive, inProgress };
+}
+
+export function __resetResourceGcForTest(): void {
+	stopTimer();
+	activeSessions.clear();
+	inProgress = false;
+	rssWarningActive = false;
+	lastScreenshotScanAt = 0;
+	deps = defaultDeps;
+}

package/src/tools/ultragoal-ask-guard.ts

@@ -1,5 +1,9 @@
 import type { AgentTool } from "@sayknow-cli/agent-core";
-import { isUltragoalAskBlocked, type UltragoalAskBlockDiagnostic } from "../skc-runtime/ultragoal-guard";
+import {
+	consumeUltragoalAskNudge,
+	isUltragoalAskBlocked,
+	type UltragoalAskBlockDiagnostic,
+} from "../skc-runtime/ultragoal-guard";
 import { ToolError } from "./tool-errors";
 
 const ULTRAGOAL_ASK_GUARD = Symbol.for("sayknow-cli.ultragoalAskGuard");
@@ -17,6 +21,8 @@ export function formatUltragoalAskBlockMessage(diagnostic: UltragoalAskBlockDiag
 export async function assertUltragoalAskAllowed(cwd: string): Promise<void> {
 	const diagnostic = await isUltragoalAskBlocked(cwd);
 	if (!diagnostic.active) return;
+	const nudge = await consumeUltragoalAskNudge(cwd);
+	if (nudge.nudged) throw new ToolError(nudge.message);
 	throw new ToolError(formatUltragoalAskBlockMessage(diagnostic));
 }
 

package/src/utils/changelog.ts

@@ -92,6 +92,14 @@ export function getDisplayChangelogEntries(): ChangelogEntry[] {
 	return parseChangelogContent(CHANGELOG_TEXT);
 }
 
+export function getInstalledVersionChangelogEntry(
+	entries: readonly ChangelogEntry[],
+	installedVersion: string,
+): ChangelogEntry | undefined {
+	const [major = 0, minor = 0, patch = 0] = installedVersion.split(".").map(Number);
+	return entries.find(entry => entry.major === major && entry.minor === minor && entry.patch === patch) ?? entries[0];
+}
+
 /**
  * Compare versions. Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
  */

package/src/web/insane/url-guard.ts

@@ -1,16 +1,13 @@
 /**
- * Public HTTP(S) URL guard for the insane-search read fallback.
+ * Public HTTP(S) URL guard for user-supplied web fetch targets.
  *
- * The vendored insane-search engine performs its own network requests (curl_cffi,
- * a real browser) entirely outside the TypeScript fetch path, so the normal
- * `loadPage()` flow cannot protect against SSRF. This guard MUST run before any
- * dependency probe or engine subprocess is spawned. It is fail-closed: anything
- * it cannot prove is a public, non-credentialed http/https target is rejected.
+ * Network-capable URL readers MUST run this guard before the first request and
+ * before following any redirect target. It is fail-closed: anything it cannot
+ * prove is a public, non-credentialed http/https target is rejected.
  *
- * It does NOT follow or re-validate redirects — the engine may follow redirects
- * internally that this guard never sees. That residual risk is documented in the
- * plan and mitigated by validating the input target and keeping the feature
- * opt-in (default off).
+ * The vendored insane-search engine performs its own redirects outside the
+ * TypeScript fetch path, so its fallback remains opt-in and is guarded before
+ * any dependency probe or engine subprocess is spawned.
  */
 import * as dns from "node:dns/promises";
 import * as net from "node:net";
@@ -105,11 +102,11 @@ export function isPrivateOrSpecialAddress(address: string): boolean {
 }
 
 /**
- * Validate that `rawUrl` is a public http/https target safe to hand to the
- * insane-search engine. Resolves DNS names and rejects any that map to a
- * private/special address. Never throws; returns a discriminated result.
+ * Validate that `rawUrl` is a public http/https target. Resolves DNS names and
+ * rejects any that map to a private/special address. Never throws; returns a
+ * discriminated result.
  */
-export async function validatePublicHttpUrlForInsane(
+export async function validatePublicHttpUrl(
 	rawUrl: string,
 	options: { resolver?: AddressResolver } = {},
 ): Promise<PublicUrlResult> {
@@ -153,3 +150,10 @@ export async function validatePublicHttpUrlForInsane(
 	}
 	return { ok: true, url, addresses };
 }
+
+export async function validatePublicHttpUrlForInsane(
+	rawUrl: string,
+	options: { resolver?: AddressResolver } = {},
+): Promise<PublicUrlResult> {
+	return validatePublicHttpUrl(rawUrl, options);
+}