@gajae-code/coding-agent 0.7.1 → 0.7.3

package/src/tools/fetch.ts

@@ -16,6 +16,8 @@ import { renderStatusLine } from "../tui";
 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 { 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";
@@ -705,6 +707,55 @@ async function handleSpecialUrls(
 // Main Render Function
 // =============================================================================
 
+/**
+ * Opt-in insane-search fallback for blocked / degraded public URL reads.
+ *
+ * Returns a finalized `method: "insane"` result on success, or null (so the
+ * caller continues with its normal degraded behavior). Fail-closed: no note,
+ * guard DNS, dependency probe, or subprocess when raw mode or the opt-in
+ * setting is off. The public-URL guard runs BEFORE any probe/spawn.
+ */
+export async function tryInsaneFallback(args: {
+	url: string;
+	finalUrl: string;
+	timeout: number;
+	raw: boolean;
+	settings: Settings;
+	signal: AbortSignal | undefined;
+	fetchedAt: string;
+	notes: string[];
+}): Promise<FetchRenderResult | null> {
+	if (args.raw) return null;
+	if (args.settings.get("web.insaneFallback") !== true) return null;
+
+	const target = args.finalUrl || args.url;
+	const guard = await validatePublicHttpUrlForInsane(target);
+	if (!guard.ok) {
+		args.notes.push(INSANE_NOTES.guardBlocked(guard.reason));
+		return null;
+	}
+
+	const result = await tryInsaneFetch(guard.url.toString(), {
+		timeoutMs: args.timeout * 1000,
+		signal: args.signal,
+	});
+	if (result.ok) {
+		const output = finalizeOutput(result.content);
+		return {
+			url: args.url,
+			finalUrl: target,
+			contentType: "text/markdown",
+			method: "insane",
+			content: output.content,
+			fetchedAt: args.fetchedAt,
+			truncated: output.truncated,
+			notes: [...args.notes, ...result.notes],
+		};
+	}
+	for (const note of result.notes) args.notes.push(note);
+	return null;
+}
+
 /**
  * Main render function implementing the full pipeline
  */
@@ -738,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) {
@@ -751,6 +817,20 @@ async function renderUrl(
 		throw new ToolAbortError();
 	}
 	if (!response.ok) {
+		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,
+			finalUrl: response.finalUrl || url,
+			timeout,
+			raw,
+			settings,
+			signal,
+			fetchedAt,
+			notes,
+		});
+		if (insane) return insane;
 		return {
 			url,
 			finalUrl: response.finalUrl || url,
@@ -759,7 +839,7 @@ async function renderUrl(
 			content: "",
 			fetchedAt,
 			truncated: false,
-			notes: [response.status ? `Failed to fetch URL (HTTP ${response.status})` : "Failed to fetch URL"],
+			notes,
 		};
 	}
 
@@ -1062,6 +1142,8 @@ async function renderUrl(
 		const htmlResult = await renderHtmlToText(finalUrl, rawContent, timeout, settings, signal, storage);
 		if (!htmlResult.ok) {
 			notes.push("html rendering failed (lynx/html2text unavailable)");
+			const insane = await tryInsaneFallback({ url, finalUrl, timeout, raw, settings, signal, fetchedAt, notes });
+			if (insane) return insane;
 			const output = finalizeOutput(rawContent);
 			return {
 				url,
@@ -1122,6 +1204,17 @@ async function renderUrl(
 				};
 			}
 
+			const insaneLowQuality = await tryInsaneFallback({
+				url,
+				finalUrl,
+				timeout,
+				raw,
+				settings,
+				signal,
+				fetchedAt,
+				notes,
+			});
+			if (insaneLowQuality) return insaneLowQuality;
 			notes.push("Page appears to require JavaScript or is mostly navigation");
 		}
 

package/src/tools/index.ts

@@ -58,6 +58,7 @@ import { SearchToolBm25Tool } from "./search-tool-bm25";
 import { SkillTool } from "./skill";
 import { loadSshTool } from "./ssh";
 import { SubagentTool } from "./subagent";
+import { TelegramSendTool } from "./telegram-send";
 import { type TodoPhase, TodoWriteTool } from "./todo-write";
 import { WriteTool } from "./write";
 import { YieldTool } from "./yield";
@@ -96,6 +97,7 @@ export * from "./search-tool-bm25";
 export * from "./skill";
 export * from "./ssh";
 export * from "./subagent";
+export * from "./telegram-send";
 export * from "./todo-write";
 export * from "./vim";
 export * from "./write";
@@ -402,6 +404,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	todo_write: s => new TodoWriteTool(s),
 	web_search: s => new WebSearchTool(s),
 	search_tool_bm25: SearchToolBm25Tool.createIf,
+	telegram_send: TelegramSendTool.createIf,
 	write: s => new WriteTool(s),
 	skill: SkillTool.createIf,
 	goal: s => new GoalTool(s),

package/src/tools/telegram-send.ts

@@ -0,0 +1,137 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import { z } from "zod/v4";
+import { getTelegramFileSink } from "../notifications/attachment-registry";
+import { getNotificationConfig, isGloballyConfigured } from "../notifications/config";
+import type { ToolSession } from "./index";
+
+const telegramSendSchema = z.object({
+	path: z
+		.string()
+		.describe("file path (absolute or relative to cwd) to send to Telegram; must resolve inside the workspace"),
+	caption: z.string().optional().describe("optional caption"),
+});
+
+type TelegramSendParams = z.infer<typeof telegramSendSchema>;
+
+interface TelegramSendDetails {
+	path: string;
+	caption?: string;
+	ok: boolean;
+	error?: string;
+}
+
+export class TelegramSendTool implements AgentTool<typeof telegramSendSchema, TelegramSendDetails> {
+	readonly name = "telegram_send";
+	readonly label = "TelegramSend";
+	readonly summary = "Send a workspace file to Telegram";
+	readonly loadMode = "discoverable";
+	readonly description =
+		"Send a file from the current workspace to the connected Telegram chat as a document. The path must resolve " +
+		"(after following symlinks) to a regular file inside the project root; paths outside the workspace are rejected.";
+	readonly parameters = telegramSendSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): TelegramSendTool | null {
+		return isGloballyConfigured(getNotificationConfig(session.settings)) ? new TelegramSendTool(session) : null;
+	}
+
+	/**
+	 * Resolve `requested` against the workspace root and confine it via realpath:
+	 * blocks absolute paths outside the project, `..` traversal, and symlinks that
+	 * escape the root. Returns the resolved real path of a regular file, or an
+	 * error message. This is the egress safety boundary — the model can only send
+	 * files that genuinely live inside the session workspace.
+	 */
+	private async resolveContainedFile(
+		requested: string,
+	): Promise<{ ok: true; path: string } | { ok: false; error: string }> {
+		let root: string;
+		try {
+			root = await fs.promises.realpath(this.session.cwd);
+		} catch {
+			return { ok: false, error: "workspace root is unavailable" };
+		}
+		const absolute = path.isAbsolute(requested) ? requested : path.resolve(root, requested);
+		let real: string;
+		try {
+			real = await fs.promises.realpath(absolute);
+		} catch {
+			return { ok: false, error: `file not found: ${requested}` };
+		}
+		const rel = path.relative(root, real);
+		if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+			return { ok: false, error: "path escapes the workspace root; only files inside the project can be sent" };
+		}
+		let stat: fs.Stats;
+		try {
+			stat = await fs.promises.stat(real);
+		} catch {
+			return { ok: false, error: `file not found: ${requested}` };
+		}
+		if (!stat.isFile()) {
+			return { ok: false, error: "not a regular file" };
+		}
+		return { ok: true, path: real };
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: TelegramSendParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<TelegramSendDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<TelegramSendDetails>> {
+		const sessionId = this.session.getSessionId?.();
+		if (!sessionId) {
+			return {
+				content: [{ type: "text", text: "telegram_send: no active session id" }],
+				details: { path: params.path, caption: params.caption, ok: false, error: "no active session id" },
+				isError: true,
+			};
+		}
+
+		const contained = await this.resolveContainedFile(params.path);
+		if (!contained.ok) {
+			return {
+				content: [{ type: "text", text: `telegram_send: ${contained.error}` }],
+				details: { path: params.path, caption: params.caption, ok: false, error: contained.error },
+				isError: true,
+			};
+		}
+		const abs = contained.path;
+
+		const sink = getTelegramFileSink(sessionId);
+		if (!sink) {
+			return {
+				content: [
+					{ type: "text", text: "telegram_send: Telegram notifications are not connected for this session" },
+				],
+				details: {
+					path: abs,
+					caption: params.caption,
+					ok: false,
+					error: "Telegram notifications are not connected",
+				},
+				isError: true,
+			};
+		}
+
+		const result = await sink({ path: abs, caption: params.caption });
+		if (result.ok) {
+			return {
+				content: [{ type: "text", text: `Sent ${path.basename(abs)} to Telegram.` }],
+				details: { path: abs, caption: params.caption, ok: true },
+			};
+		}
+
+		return {
+			content: [{ type: "text", text: `telegram_send failed: ${result.error}` }],
+			details: { path: abs, caption: params.caption, ok: false, error: result.error },
+			isError: true,
+		};
+	}
+}

package/src/web/insane/bridge.ts

@@ -0,0 +1,350 @@
+/**
+ * Bridge from TypeScript to the vendored insane-search Python engine.
+ *
+ * Invokes `python3 -m engine "<url>" --json` per fallback attempt (cwd + PYTHONPATH
+ * pointed at the vendored engine), validates the JSON envelope, and maps it onto a
+ * discriminated result. Hardened: clamped timeout, AbortSignal propagation that
+ * kills+reaps the child, bounded stdout/stderr capture, and a per-process
+ * concurrency cap so blocked reads cannot fork-storm.
+ *
+ * Fail-closed: missing dependencies / bad output / auth-required never throw past
+ * the caller and never auto-install anything; they return ok:false with a stable,
+ * bounded note so `read` can continue with its normal degraded result.
+ */
+import { type ChildProcess, spawn as nodeSpawn } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { $which } from "@gajae-code/utils";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** packages/coding-agent/vendor/insane-search */
+export const INSANE_VENDOR_DIR = path.resolve(HERE, "../../../vendor/insane-search");
+const TEMPLATES_DIR = path.join(INSANE_VENDOR_DIR, "engine", "templates");
+
+const MAX_STDOUT_BYTES = 8 * 1024 * 1024;
+const MAX_STDERR_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 25_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 120_000;
+const DEFAULT_CONCURRENCY = 2;
+const KILL_GRACE_MS = 2_000;
+
+/** Stable note prefixes — tests assert on these without depending on full stderr. */
+export const INSANE_NOTES = {
+	guardBlocked: (reason: string) => `insane fallback blocked: target URL is not public HTTP(S): ${reason}`,
+	vendorMissing: `insane fallback unavailable: vendor engine missing at packages/coding-agent/vendor/insane-search`,
+	noPython: `insane fallback unavailable: python3 not found; install python3 and curl_cffi, then retry with web.insaneFallback=true`,
+	noCurlCffi: `insane fallback unavailable: python3 cannot import curl_cffi; install curl_cffi for Phase 0-2`,
+	noBrowser: `insane fallback unavailable: node/playwright/stealth dependencies missing for Phase 3; install dependencies under packages/coding-agent/vendor/insane-search/engine/templates`,
+	timeout: (seconds: number) => `insane fallback timed out after ${seconds}s; normal read fallback preserved`,
+	invalidJson: `insane fallback failed: engine returned invalid JSON`,
+	authRequired: `insane fallback stopped: authentication required`,
+	verdict: (verdict: string) => `insane fallback failed: engine returned verdict=${verdict}`,
+	untried: (routes: string) => `insane fallback routes not tried: ${routes}`,
+	mustBrowserMcp: `insane fallback requires browser MCP/manual phase: must_invoke_playwright_mcp=true`,
+	concurrency: `insane fallback skipped: max concurrent engine attempts reached`,
+	emptyContent: `insane fallback failed: engine reported ok but returned no content`,
+} as const;
+
+/** Raw JSON envelope produced by `python3 -m engine --json`. */
+export interface InsaneFetchResultRaw {
+	ok?: boolean;
+	verdict?: string;
+	content?: string;
+	profile_used?: string;
+	trace?: unknown;
+	untried_routes?: string[];
+	must_invoke_playwright_mcp?: boolean;
+}
+
+export interface InsaneSuccess {
+	ok: true;
+	content: string;
+	profileUsed?: string;
+	notes: string[];
+}
+
+export interface InsaneFailure {
+	ok: false;
+	reason: string;
+	verdict?: string;
+	notes: string[];
+}
+
+export type InsaneBridgeResult = InsaneSuccess | InsaneFailure;
+
+export interface EngineInvocation {
+	url: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+}
+
+export interface EngineRawOutput {
+	code: number | null;
+	stdout: string;
+	stderr: string;
+	timedOut: boolean;
+	aborted: boolean;
+}
+
+/** Seam: run the engine subprocess. Default spawns python3. */
+export type EngineRunner = (inv: EngineInvocation) => Promise<EngineRawOutput>;
+
+export interface InsaneDependencyStatus {
+	vendorPresent: boolean;
+	python: boolean;
+	curlCffi: boolean;
+	browser: boolean;
+}
+
+/** Seam: probe dependencies. Default probes the real environment (cached). */
+export type DependencyProber = () => Promise<InsaneDependencyStatus>;
+
+// ---------------------------------------------------------------------------
+// Subprocess runner
+// ---------------------------------------------------------------------------
+
+type SpawnImpl = typeof nodeSpawn;
+
+function clampTimeoutMs(timeoutMs: number | undefined): number {
+	const value = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	if (!Number.isFinite(value)) return DEFAULT_TIMEOUT_MS;
+	return Math.max(MIN_TIMEOUT_MS, Math.min(MAX_TIMEOUT_MS, Math.floor(value)));
+}
+
+function appendCapped(buffer: string, chunk: string, cap: number): string {
+	if (buffer.length >= cap) return buffer;
+	const remaining = cap - buffer.length;
+	return buffer + (chunk.length > remaining ? chunk.slice(0, remaining) : chunk);
+}
+
+/** Kill a child and its group, escalating to SIGKILL after a grace period. */
+function killChild(child: ChildProcess): void {
+	try {
+		child.kill("SIGTERM");
+	} catch {
+		// already gone
+	}
+	const timer = setTimeout(() => {
+		try {
+			child.kill("SIGKILL");
+		} catch {
+			// already gone
+		}
+	}, KILL_GRACE_MS);
+	timer.unref?.();
+	child.once("exit", () => clearTimeout(timer));
+}
+
+/** Real engine runner: `python3 -m engine "<url>" --json`. */
+export function runEngineSubprocess(
+	inv: EngineInvocation,
+	options: { spawnImpl?: SpawnImpl } = {},
+): Promise<EngineRawOutput> {
+	const spawnImpl = options.spawnImpl ?? nodeSpawn;
+	return new Promise<EngineRawOutput>(resolve => {
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timedOut = false;
+		let aborted = false;
+
+		const child = spawnImpl("python3", ["-m", "engine", inv.url, "--json"], {
+			cwd: INSANE_VENDOR_DIR,
+			env: { ...process.env, PYTHONPATH: INSANE_VENDOR_DIR },
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const finish = (code: number | null): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			inv.signal?.removeEventListener("abort", onAbort);
+			resolve({ code, stdout, stderr, timedOut, aborted });
+		};
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			killChild(child);
+		}, inv.timeoutMs);
+		timer.unref?.();
+
+		const onAbort = (): void => {
+			aborted = true;
+			killChild(child);
+		};
+		if (inv.signal) {
+			if (inv.signal.aborted) onAbort();
+			else inv.signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			stdout = appendCapped(stdout, chunk.toString("utf8"), MAX_STDOUT_BYTES);
+		});
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr = appendCapped(stderr, chunk.toString("utf8"), MAX_STDERR_BYTES);
+		});
+		child.on("error", () => finish(null));
+		child.on("close", code => finish(code));
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Dependency probes (cached)
+// ---------------------------------------------------------------------------
+
+let probeCache: Promise<InsaneDependencyStatus> | null = null;
+
+/** Reset the probe cache between tests so probe state never leaks. */
+export function resetInsaneProbeCacheForTest(): void {
+	probeCache = null;
+}
+
+function runProbeCommand(cmd: string, args: string[], cwd?: string): Promise<boolean> {
+	return new Promise<boolean>(resolve => {
+		let settled = false;
+		const done = (ok: boolean): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(ok);
+		};
+		const child = nodeSpawn(cmd, args, { cwd, stdio: "ignore" });
+		const timer = setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {
+				// gone
+			}
+			done(false);
+		}, 10_000);
+		timer.unref?.();
+		child.on("error", () => done(false));
+		child.on("close", code => done(code === 0));
+	});
+}
+
+async function probeRealDependencies(): Promise<InsaneDependencyStatus> {
+	const { existsSync } = await import("node:fs");
+	const vendorPresent = existsSync(path.join(INSANE_VENDOR_DIR, "engine", "__main__.py"));
+	if (!vendorPresent) {
+		return { vendorPresent: false, python: false, curlCffi: false, browser: false };
+	}
+	const python = Boolean($which("python3"));
+	const curlCffi = python ? await runProbeCommand("python3", ["-c", "import curl_cffi"]) : false;
+	const node = Boolean($which("node"));
+	const browser = node
+		? await runProbeCommand(
+				"node",
+				[
+					"-e",
+					"require.resolve('playwright');require.resolve('playwright-extra');require.resolve('puppeteer-extra-plugin-stealth')",
+				],
+				TEMPLATES_DIR,
+			)
+		: false;
+	return { vendorPresent, python, curlCffi, browser };
+}
+
+/** Probe (and cache) the insane-search runtime dependencies. */
+export function probeInsaneDependencies(): Promise<InsaneDependencyStatus> {
+	if (!probeCache) probeCache = probeRealDependencies();
+	return probeCache;
+}
+
+// ---------------------------------------------------------------------------
+// Concurrency gate
+// ---------------------------------------------------------------------------
+
+let inFlight = 0;
+
+export function resetInsaneConcurrencyForTest(): void {
+	inFlight = 0;
+}
+
+// ---------------------------------------------------------------------------
+// High-level bridge
+// ---------------------------------------------------------------------------
+
+export interface TryInsaneFetchOptions {
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	concurrencyLimit?: number;
+	/** Seam: dependency prober (default real, cached). */
+	prober?: DependencyProber;
+	/** Seam: engine runner (default real subprocess). */
+	runner?: EngineRunner;
+}
+
+function mapEngineOutput(raw: EngineRawOutput, timeoutMs: number): InsaneBridgeResult {
+	const notes: string[] = [];
+	if (raw.aborted) {
+		return { ok: false, reason: "aborted", notes };
+	}
+	if (raw.timedOut) {
+		notes.push(INSANE_NOTES.timeout(Math.round(timeoutMs / 1000)));
+		return { ok: false, reason: "timeout", notes };
+	}
+	let parsed: InsaneFetchResultRaw;
+	try {
+		parsed = JSON.parse(raw.stdout) as InsaneFetchResultRaw;
+	} catch {
+		notes.push(INSANE_NOTES.invalidJson);
+		return { ok: false, reason: "invalid-json", notes };
+	}
+
+	const verdict = parsed.verdict?.trim();
+	// The engine emits the Verdict enum value `auth_required` (401/407); also tolerate
+	// the human-readable phrase defensively. Either is a terminal public-content boundary.
+	if (verdict && /^(?:auth_required|authentication required)$/i.test(verdict)) {
+		notes.push(INSANE_NOTES.authRequired);
+		return { ok: false, reason: "auth-required", verdict, notes };
+	}
+
+	if (parsed.untried_routes && parsed.untried_routes.length > 0) {
+		notes.push(INSANE_NOTES.untried(parsed.untried_routes.slice(0, 8).join(", ")));
+	}
+	if (parsed.must_invoke_playwright_mcp) {
+		notes.push(INSANE_NOTES.mustBrowserMcp);
+	}
+
+	if (parsed.ok && typeof parsed.content === "string" && parsed.content.trim().length > 0) {
+		return { ok: true, content: parsed.content, profileUsed: parsed.profile_used, notes };
+	}
+	if (parsed.ok) {
+		notes.push(INSANE_NOTES.emptyContent);
+		return { ok: false, reason: "empty-content", notes };
+	}
+	notes.push(INSANE_NOTES.verdict(verdict || "unknown"));
+	return { ok: false, reason: "engine-failed", verdict, notes };
+}
+
+/**
+ * Attempt to read `url` through the insane-search engine. The caller is
+ * responsible for the opt-in gate, raw-mode skip, and the public-URL guard
+ * (which MUST run before this is called). Never throws; always returns a result.
+ */
+export async function tryInsaneFetch(url: string, options: TryInsaneFetchOptions = {}): Promise<InsaneBridgeResult> {
+	const prober = options.prober ?? probeInsaneDependencies;
+	const runner = options.runner ?? (inv => runEngineSubprocess(inv));
+	const limit = options.concurrencyLimit ?? DEFAULT_CONCURRENCY;
+
+	const deps = await prober();
+	if (!deps.vendorPresent) return { ok: false, reason: "vendor-missing", notes: [INSANE_NOTES.vendorMissing] };
+	if (!deps.python) return { ok: false, reason: "no-python", notes: [INSANE_NOTES.noPython] };
+	if (!deps.curlCffi) return { ok: false, reason: "no-curl-cffi", notes: [INSANE_NOTES.noCurlCffi] };
+	if (!deps.browser) return { ok: false, reason: "no-browser", notes: [INSANE_NOTES.noBrowser] };
+
+	if (inFlight >= limit) {
+		return { ok: false, reason: "concurrency", notes: [INSANE_NOTES.concurrency] };
+	}
+
+	inFlight++;
+	try {
+		const timeoutMs = clampTimeoutMs(options.timeoutMs);
+		const raw = await runner({ url, timeoutMs, signal: options.signal });
+		return mapEngineOutput(raw, timeoutMs);
+	} finally {
+		inFlight--;
+	}
+}