@browserwright/pi 0.0.1

package/core/exec-http.ts

@@ -0,0 +1,138 @@
+/**
+ * The "http" provider kind: one request, optionally pluck a field out of JSON.
+ * Covers jina, both Cloudflare markdown endpoints, and the shape every other
+ * hosted reader API happens to have.
+ */
+
+import { interpolate, interpolateEnv, pickPath, subjectTokens } from "./predicates.ts";
+import { normalizeSearchPayload } from "./results.ts";
+import type { HttpProvider, ProviderOutcome, Role } from "./types.ts";
+
+/** Interpolate the subject tokens then $ENV, collecting unset variable names. */
+function fill(
+	template: string,
+	tokens: Record<string, string>,
+	env: Record<string, string | undefined>,
+	missing: string[],
+): string {
+	const resolved = interpolateEnv(interpolate(template, tokens), env);
+	missing.push(...resolved.missing);
+	return resolved.value;
+}
+
+function fillBody(
+	body: unknown,
+	tokens: Record<string, string>,
+	env: Record<string, string | undefined>,
+	missing: string[],
+): unknown {
+	if (typeof body === "string") return fill(body, tokens, env, missing);
+	if (Array.isArray(body)) return body.map((item) => fillBody(item, tokens, env, missing));
+	if (body && typeof body === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(body)) {
+			out[key] = fillBody(value, tokens, env, missing);
+		}
+		return out;
+	}
+	return body;
+}
+
+export async function execHttp(
+	provider: HttpProvider,
+	subject: string,
+	options: {
+		dir: string;
+		role: Role;
+		timeoutMs: number;
+		signal?: AbortSignal;
+		env?: Record<string, string | undefined>;
+	},
+): Promise<ProviderOutcome<unknown>> {
+	const env = options.env ?? process.env;
+	const missing: string[] = [];
+	const tokens = subjectTokens(options.role, subject, options.dir);
+
+	const target = fill(provider.url, tokens, env, missing);
+	const headers: Record<string, string> = {};
+	for (const [key, value] of Object.entries(provider.headers ?? {})) {
+		headers[key] = fill(value, tokens, env, missing);
+	}
+	const body = provider.body === undefined ? undefined : fillBody(provider.body, tokens, env, missing);
+
+	// A provider that references an unset key is not a failure to report, it is
+	// a rung that does not exist on this machine. Say so plainly and move on.
+	if (missing.length > 0) {
+		return { ok: false, reason: `missing env ${[...new Set(missing)].join(", ")}` };
+	}
+
+	const timeout = AbortSignal.timeout(provider.timeoutMs ?? options.timeoutMs);
+	const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+
+	let response: Response;
+	try {
+		response = await fetch(target, {
+			method: provider.method ?? "GET",
+			headers,
+			body: body === undefined ? undefined : JSON.stringify(body),
+			signal,
+			redirect: "follow",
+		});
+	} catch (error) {
+		const message = (error as Error).name === "TimeoutError" ? "timeout" : (error as Error).message;
+		return { ok: false, reason: message };
+	}
+
+	const text = await response.text();
+
+	if (!response.ok) {
+		// Include a slice of the body: Cloudflare puts the actionable part
+		// ("Authentication error") there, not in the status line.
+		const hint = text.slice(0, 200).replace(/\s+/g, " ").trim();
+		return { ok: false, status: response.status, reason: `http ${response.status}${hint ? `: ${hint}` : ""}` };
+	}
+
+	if (!provider.pick) {
+		// A search provider that plucks nothing still has to hand back rows, not
+		// the raw body, or the chain would inspect a JSON string as if it were prose.
+		if (options.role === "search") {
+			try {
+				return { ok: true, content: normalizeSearchPayload(JSON.parse(text)), status: response.status };
+			} catch {
+				return { ok: false, status: response.status, reason: "search provider returned a non-JSON body" };
+			}
+		}
+		return { ok: true, content: text, status: response.status };
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return { ok: false, status: response.status, reason: `pick "${provider.pick}" needs JSON, got non-JSON body` };
+	}
+
+	const picked = pickPath(parsed, provider.pick);
+	const errors = (parsed as { errors?: unknown })?.errors;
+	const detail = errors ? ` (errors: ${JSON.stringify(errors).slice(0, 200)})` : "";
+
+	// A fetch provider plucks one string; a search provider plucks a list. The
+	// old code assumed the former unconditionally, which meant any list-shaped
+	// API failed here with a misleading "no string at" before its rows were seen.
+	if (options.role === "search") {
+		if (!Array.isArray(picked)) {
+			return { ok: false, status: response.status, reason: `no array at "${provider.pick}"${detail}` };
+		}
+		// `pick` names the organic rows; the SERP-feature fields, if the API
+		// returned any, still come from the top level of the same body.
+		const payload = normalizeSearchPayload(parsed);
+		payload.results = normalizeResults(picked);
+		return { ok: true, content: payload, status: response.status };
+	}
+
+	if (typeof picked !== "string") {
+		return { ok: false, status: response.status, reason: `no string at "${provider.pick}"${detail}` };
+	}
+
+	return { ok: true, content: picked, status: response.status };
+}

package/core/exec-module.ts

@@ -0,0 +1,95 @@
+/**
+ * The "module" provider kind: hand off to a TS module inside this package.
+ *
+ * This is the escape hatch for a provider that cannot be expressed as one shot
+ * at a subprocess — one that owns a multi-step lifecycle, retries on its own,
+ * or reports progress while it works. A `kind: "command"` provider gets exactly
+ * one process and one exit code; a module gets the event loop.
+ *
+ * The contract is deliberately the same as the other two kinds from the
+ * engine's point of view: it returns a ProviderOutcome and never throws past
+ * this file, so a broken runner drops a rung instead of failing the whole call.
+ *
+ * Cancellation is cooperative. Unlike a subprocess there is nothing to SIGKILL,
+ * so the runner is handed an AbortSignal that fires on either the caller's
+ * abort or the timeout, and is expected to unwind its own resources. The race
+ * below only bounds how long the engine waits — a runner that ignores its
+ * signal will keep running in the background, which is why every runner in this
+ * package cleans up in a `finally`.
+ */
+
+import { pathToFileURL } from "node:url";
+import { isAbsolute, resolve } from "node:path";
+import type { ModuleContext, ModuleProvider, ModuleRunner, ProviderOutcome, Role } from "./types.ts";
+
+const cache = new Map<string, ModuleRunner<unknown>>();
+
+async function loadRunner(spec: string, dir: string): Promise<ModuleRunner<unknown>> {
+	const cached = cache.get(spec);
+	if (cached) return cached;
+
+	const path = isAbsolute(spec) ? spec : resolve(dir, spec);
+	const imported = (await import(pathToFileURL(path).href)) as { default?: unknown };
+	const runner = imported.default;
+	if (typeof runner !== "function") {
+		throw new Error(`${spec} does not default-export a runner function`);
+	}
+	cache.set(spec, runner as ModuleRunner<unknown>);
+	return runner as ModuleRunner<unknown>;
+}
+
+export async function execModule<T>(
+	provider: ModuleProvider,
+	subject: string,
+	options: {
+		dir: string;
+		role: Role;
+		timeoutMs: number;
+		signal?: AbortSignal;
+		onProgress?: (text: string) => void;
+	},
+): Promise<ProviderOutcome<T>> {
+	if (!provider.module) return { ok: false, reason: "module provider has no `module` path" };
+
+	if (options.signal?.aborted) return { ok: false, reason: "aborted" };
+
+	const timeoutMs = provider.timeoutMs ?? options.timeoutMs;
+	const controller = new AbortController();
+	const onOuterAbort = () => controller.abort();
+	// Registering on an already-aborted signal never fires, so the check above is
+	// what actually handles "cancelled before we started".
+	options.signal?.addEventListener("abort", onOuterAbort, { once: true });
+
+	let timer: NodeJS.Timeout | undefined;
+	const deadline = new Promise<ProviderOutcome<T>>((res) => {
+		timer = setTimeout(() => {
+			controller.abort();
+			res({ ok: false, reason: `timeout after ${timeoutMs}ms` });
+		}, timeoutMs);
+	});
+
+	try {
+		const runner = await loadRunner(provider.module, options.dir);
+		const ctx: ModuleContext = {
+			dir: options.dir,
+			timeoutMs,
+			signal: controller.signal,
+			options: provider.options ?? {},
+			onProgress: options.onProgress,
+		};
+		const running = (async () => {
+			try {
+				return (await runner(subject, ctx)) as ProviderOutcome<T>;
+			} catch (error) {
+				return { ok: false, reason: (error as Error).message } as ProviderOutcome<T>;
+			}
+		})();
+		return await Promise.race([running, deadline]);
+	} catch (error) {
+		// Only reachable from loadRunner — a missing file or a bad default export.
+		return { ok: false, reason: `module load failed: ${(error as Error).message}` };
+	} finally {
+		if (timer) clearTimeout(timer);
+		options.signal?.removeEventListener("abort", onOuterAbort);
+	}
+}

package/core/format.ts

@@ -0,0 +1,211 @@
+/**
+ * Turning a ChainResult into the text the model sees.
+ *
+ * Everything the model needs to act on has to be in `content` — pi's tool
+ * `details` field never reaches the LLM, it only feeds the TUI renderer. So the
+ * provider name, the format, and the escalation hint all live in the text.
+ */
+
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Attempt, ChainResult, ReturnFormat, SearchPayload } from "./types.ts";
+
+/** Pull a title out of the content itself rather than fetching one. */
+export function extractTitle(content: string, format: ReturnFormat): string | undefined {
+	if (format === "html") {
+		const match = content.match(/<title[^>]*>([\s\S]{0,300}?)<\/title>/i);
+		const title = match?.[1]?.replace(/\s+/g, " ").trim();
+		return title || undefined;
+	}
+	// Providers announce the title before the body and each does it differently:
+	// jina writes a "Title: …" preamble, Cloudflare emits YAML frontmatter. Both
+	// beat the first heading, which is often a table of contents ("# Contents"
+	// on Wikipedia).
+	const head = content.slice(0, 400);
+	const declared = (head.match(/^Title:\s*(.+)$/m) ?? head.match(/^title:\s*(.+)$/m))?.[1]
+		?.trim()
+		.replace(/^"(.*)"$/, "$1")
+		.trim();
+	if (declared) return declared;
+
+	const heading = content.match(/^#{1,2}\s+(.+)$/m);
+	const title = heading?.[1]?.trim();
+	return title || undefined;
+}
+
+/** "browserwright✗1.1s browserwright-search✓2.4s" — only rungs actually called. */
+export function formatChain(attempts: Attempt[]): string {
+	return attempts
+		.filter((attempt) => !attempt.skipped)
+		.map((attempt) => `${attempt.provider}${attempt.ok ? "✓" : "✗"}${(attempt.ms / 1000).toFixed(1)}s`)
+		.join(" ");
+}
+
+function humanSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+export interface RenderOptions {
+	url: string;
+	maxBytes: number;
+	maxLines: number;
+	/** Injected so tests do not touch the filesystem. */
+	writeOverflow?: (content: string) => string;
+}
+
+function defaultWriteOverflow(content: string): string {
+	const name = `browserwright-pi-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.txt`;
+	const path = join(tmpdir(), name);
+	writeFileSync(path, content, "utf8");
+	return path;
+}
+
+/** Truncate on a line boundary, keeping the head. */
+function truncate(content: string, maxBytes: number, maxLines: number) {
+	const lines = content.split("\n");
+	const kept: string[] = [];
+	let bytes = 0;
+	for (const line of lines) {
+		const size = Buffer.byteLength(line, "utf8") + 1;
+		if (kept.length >= maxLines || bytes + size > maxBytes) break;
+		kept.push(line);
+		bytes += size;
+	}
+	return {
+		content: kept.join("\n"),
+		truncated: kept.length < lines.length,
+		keptLines: kept.length,
+		totalLines: lines.length,
+		keptBytes: bytes,
+		totalBytes: Buffer.byteLength(content, "utf8"),
+	};
+}
+
+/** The fetch success path. Header first, so it survives truncation of the body. */
+export function renderSuccess(result: ChainResult<string>, options: RenderOptions): string {
+	const content = result.content ?? "";
+	const format = result.format ?? "text";
+	const cut = truncate(content, options.maxBytes, options.maxLines);
+
+	const header: string[] = [];
+	const title = extractTitle(content, format);
+	if (title) header.push(`# ${title}`);
+	header.push(options.url);
+
+	const meta = [`provider=${result.provider}`, `format=${format}`, humanSize(cut.totalBytes)];
+	header.push(meta.join(" · "));
+
+	// Only worth the tokens when more than one rung was actually tried.
+	const called = result.attempts.filter((attempt) => !attempt.skipped);
+	if (called.length > 1) header.push(`chain: ${formatChain(result.attempts)}`);
+
+	if (cut.truncated) {
+		const path = (options.writeOverflow ?? defaultWriteOverflow)(content);
+		header.push(
+			`truncated: ${cut.keptLines} of ${cut.totalLines} lines (${humanSize(cut.keptBytes)} of ${humanSize(cut.totalBytes)}) · full: ${path}`,
+		);
+	}
+
+	return `${header.join("\n")}\n\n${cut.content}`;
+}
+
+/** The engine's answer can run long; the model asked for links, not an essay. */
+const ANSWER_BOX_CAP = 1200;
+
+/**
+ * The search success path. Links plus whatever SERP features the query
+ * triggered — but never page bodies: `web_fetch` already does that, and the
+ * model is in a better position to decide which two of ten links are worth the
+ * tokens.
+ *
+ * Every section below the results is optional and most queries trigger none of
+ * them, so each is omitted entirely rather than rendered empty.
+ */
+export function renderResults(result: ChainResult<SearchPayload>, query: string): string {
+	const payload = result.content ?? { results: [] };
+	const results = payload.results;
+	const out: string[] = [`# ${results.length} results for ${JSON.stringify(query)}`, `provider=${result.provider}`];
+
+	const called = result.attempts.filter((attempt) => !attempt.skipped);
+	if (called.length > 1) out.push(`chain: ${formatChain(result.attempts)}`);
+
+	if (payload.answerBox) {
+		const label = payload.answerBox.kind === "ai-overview" ? "AI Overview" : "Featured snippet";
+		const text = truncateChars(payload.answerBox.text, ANSWER_BOX_CAP);
+		// Attributed, because it is the engine's claim and not a source the
+		// model can go read — unlike everything else on this page.
+		out.push("", `## ${label} (generated by the search engine, unsourced)`, text);
+	}
+
+	const graph = payload.knowledgeGraph;
+	if (graph) {
+		const lines: string[] = [];
+		// Each part is labelled rather than run together. An earlier version
+		// joined title and subtitle with an em dash and left the description as a
+		// bare next line; a model reading that took the whole first line as the
+		// title and the description as the subtitle.
+		if (graph.title) lines.push(`title: ${graph.title}`);
+		if (graph.subtitle) lines.push(`type: ${graph.subtitle}`);
+		if (graph.description) lines.push(`description: ${graph.description}`);
+		for (const [key, value] of Object.entries(graph.attributes ?? {})) lines.push(`${key}: ${value}`);
+		if (lines.length > 0) out.push("", "## Knowledge panel", ...lines);
+	}
+
+	if (results.length > 0) {
+		out.push("");
+		for (const row of results) {
+			out.push(`${row.position}. ${row.title}`, `   ${row.url}`);
+			const tail = [row.date, row.snippet].filter(Boolean).join(" · ");
+			if (tail) out.push(`   ${tail}`);
+			out.push("");
+		}
+	}
+
+	if (payload.peopleAlsoAsk?.length) {
+		out.push("## People also ask", ...payload.peopleAlsoAsk.map((q) => `- ${q}`), "");
+	}
+	if (payload.relatedSearches?.length) {
+		out.push("## Related searches", payload.relatedSearches.join(" · "), "");
+	}
+
+	out.push("Use web_fetch on a URL above to read it.");
+	return out.join("\n");
+}
+
+function truncateChars(text: string, cap: number): string {
+	if (text.length <= cap) return text;
+	return `${text.slice(0, cap).trimEnd()}… [truncated]`;
+}
+
+export interface FailureOptions {
+	/** Tool name, so the first line names what actually failed. */
+	tool: string;
+	/**
+	 * Provider names the model could force instead. Generated from the loaded
+	 * declarations rather than written into this file — hardcoding them here is
+	 * what previously kept naming a `curl` rung that no longer existed.
+	 */
+	alternatives?: string[];
+}
+
+/** The failure path. Must tell the model how to escalate, when it can. */
+export function renderFailure(result: ChainResult<unknown>, subject: string, options: FailureOptions): string {
+	const lines = [`${options.tool} failed for ${subject}`, ""];
+	for (const attempt of result.attempts) {
+		const marker = attempt.skipped ? "skipped" : `${(attempt.ms / 1000).toFixed(1)}s`;
+		lines.push(`  ${attempt.provider}: ${attempt.reason ?? "failed"} (${marker})`);
+	}
+
+	const untried = (options.alternatives ?? []).filter(
+		(name) => !result.attempts.some((attempt) => attempt.provider === name && !attempt.skipped),
+	);
+	if (untried.length > 0) {
+		const list = untried.map((name) => `provider=${JSON.stringify(name)}`).join(" or ");
+		lines.push("", `Retry with ${list} to force a specific rung.`);
+	}
+
+	return lines.join("\n");
+}

package/core/predicates.ts

@@ -0,0 +1,228 @@
+/**
+ * Pure predicate and interpolation helpers.
+ *
+ * Everything in here is a total function over plain data, which is the whole
+ * point: the fallback engine's decisions are the part of this extension that
+ * fails silently when it is wrong (a rung that is never tried, or garbage
+ * accepted as success), so it is the part that gets unit tests.
+ */
+
+import type { FailWhen, Inspected, Inspector, Provider, Role, SearchPayload, SubjectMatch } from "./types.ts";
+
+/** Translate a `*`-glob into a RegExp anchored at both ends. */
+export function globToRegExp(glob: string): RegExp {
+	const escaped = glob.replace(/[.+^${}()|[\]\\?]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+export function globMatchesAny(value: string, globs: string[]): boolean {
+	return globs.some((g) => globToRegExp(g).test(value));
+}
+
+function hostOf(subject: string): string {
+	try {
+		return new URL(subject).hostname;
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Evaluate a `when` predicate. An absent or empty match means "applicable".
+ * Positive fields are OR-ed together; `not` inverts a nested match.
+ *
+ * The subject is a URL for fetch providers and the raw query for search ones;
+ * `hostGlob` simply never matches in the latter case rather than throwing.
+ */
+export function matchesSubject(subject: string, match: SubjectMatch | undefined): boolean {
+	if (!match) return true;
+
+	const positives: boolean[] = [];
+	if (match.urlGlob?.length) positives.push(globMatchesAny(subject, match.urlGlob));
+	if (match.hostGlob?.length) positives.push(globMatchesAny(hostOf(subject), match.hostGlob));
+
+	if (match.not && matchesSubject(subject, match.not)) return false;
+	if (positives.length === 0) return true;
+	return positives.some(Boolean);
+}
+
+/**
+ * Merge the core default defence with a provider's own, field by field.
+ * A field present on the provider REPLACES the default; it does not merge.
+ * That is what makes `{"matches": []}` a working opt-out.
+ */
+export function resolveFailWhen(defaults: FailWhen, own: FailWhen | undefined): FailWhen {
+	return {
+		minChars: own?.minChars ?? defaults.minChars ?? 0,
+		minResults: own?.minResults ?? defaults.minResults ?? 0,
+		matches: own?.matches ?? defaults.matches ?? [],
+	};
+}
+
+/** A text payload: the whole blob is the haystack, and it has no item count. */
+export const inspectText: Inspector<string> = (content) => ({ text: content });
+
+/**
+ * A search payload. The haystack is result titles and snippets joined —
+ * deliberately not the serialized JSON, because needles would then match
+ * structural punctuation and field names rather than what the page said.
+ *
+ * The count is organic rows only. The optional SERP features are bonuses that
+ * most queries do not trigger, so counting them would make `minResults` mean
+ * something different from one query to the next.
+ */
+export const inspectSearch: Inspector<SearchPayload> = (payload) => ({
+	count: payload.results.length,
+	text: payload.results.map((r) => `${r.title} ${r.snippet ?? ""}`).join("\n"),
+});
+
+/**
+ * Decide whether a payload that a provider reported as successful should still
+ * be rejected. Returns a human-readable reason, or undefined to accept.
+ *
+ * `inspect` reduces the payload to text plus an optional item count, so the
+ * same rule set guards a Markdown blob and a list of search results.
+ */
+export function failureReason<T>(value: T, rule: FailWhen, inspect: Inspector<T>): string | undefined {
+	const inspected: Inspected = inspect(value);
+	const trimmed = inspected.text.trim();
+	const count = inspected.count;
+
+	if (count !== undefined) {
+		// A search that parsed cleanly but found nothing is a failure worth
+		// falling through on: an interstitial usually yields a valid, empty list
+		// rather than an error.
+		if (count === 0) return "no results";
+		const minResults = rule.minResults ?? 0;
+		if (minResults > 0 && count < minResults) {
+			return `too few results (${count} < ${minResults})`;
+		}
+	} else {
+		if (trimmed.length === 0) return "empty response";
+		// minChars measures a prose blob, so it is deliberately not applied to a
+		// list: the floor that means anything there is minResults. Applying both
+		// would let a short-but-complete set of hits be rejected for its length.
+		const min = rule.minChars ?? 0;
+		if (min > 0 && trimmed.length < min) {
+			return `too short (${trimmed.length} chars < ${min})`;
+		}
+	}
+
+	const haystack = trimmed.toLowerCase();
+	for (const needle of rule.matches ?? []) {
+		if (!needle) continue;
+		if (haystack.includes(needle.toLowerCase())) return `matched ${JSON.stringify(needle)}`;
+	}
+
+	return undefined;
+}
+
+/**
+ * Substitute $ENV_VAR references from `env`. Literal values pass through
+ * untouched, which is the documented way to put an API key straight into a
+ * provider declaration.
+ *
+ * Returns the missing variable names so a provider that references an unset
+ * key can be skipped rather than sending the literal string "$TOKEN".
+ */
+export function interpolateEnv(
+	value: string,
+	env: Record<string, string | undefined>,
+): { value: string; missing: string[] } {
+	const missing: string[] = [];
+	const out = value.replace(/\$([A-Z0-9_]+)/g, (whole, name: string) => {
+		const found = env[name];
+		if (found === undefined || found === "") {
+			missing.push(name);
+			return whole;
+		}
+		return found;
+	});
+	return { value: out, missing };
+}
+
+/**
+ * Fill {token} placeholders. Longer names are substituted first so that
+ * {urlEncoded} wins over {url} — otherwise the shorter token would eat its
+ * own prefix and leave a stray "Encoded" behind.
+ */
+export function interpolate(template: string, tokens: Record<string, string>): string {
+	let out = template;
+	for (const key of Object.keys(tokens).sort((a, b) => b.length - a.length)) {
+		out = out.replaceAll(`{${key}}`, tokens[key]);
+	}
+	return out;
+}
+
+/**
+ * The tokens a provider of this role may use. A fetch provider gets {url};
+ * a search provider gets {query}. Both get the encoded variant and {dir}.
+ */
+export function subjectTokens(role: Role, subject: string, dir: string): Record<string, string> {
+	const key = role === "search" ? "query" : "url";
+	return {
+		[key]: subject,
+		[`${key}Encoded`]: encodeURIComponent(subject),
+		dir,
+	};
+}
+
+/** A provider's role, defaulting to fetch so an older declaration still loads. */
+export function roleOf(provider: Provider): Role {
+	return provider.role ?? "fetch";
+}
+
+export function providersForRole(providers: Map<string, Provider>, role: Role): Map<string, Provider> {
+	return new Map([...providers].filter(([, provider]) => roleOf(provider) === role));
+}
+
+/**
+ * Order the providers for one request: config order first, then drop the
+ * disabled ones and the ones whose `when` says they cannot serve this subject.
+ *
+ * When `forced` is set, only that provider is returned and no fallback
+ * happens — an explicit provider choice from the model is taken literally.
+ */
+export function selectProviders(
+	providers: Map<string, Provider>,
+	order: string[],
+	subject: string,
+	forced?: string,
+): { chain: Provider[]; skipped: Array<{ name: string; reason: string }> } {
+	const skipped: Array<{ name: string; reason: string }> = [];
+
+	if (forced) {
+		const one = providers.get(forced);
+		if (!one) return { chain: [], skipped: [{ name: forced, reason: "unknown provider" }] };
+		return { chain: [one], skipped };
+	}
+
+	const names = [...order, ...[...providers.keys()].filter((n) => !order.includes(n))];
+	const chain: Provider[] = [];
+
+	for (const name of names) {
+		const provider = providers.get(name);
+		if (!provider) continue;
+		if (provider.enabled === false) {
+			skipped.push({ name, reason: "disabled" });
+			continue;
+		}
+		if (!matchesSubject(subject, provider.when)) {
+			skipped.push({ name, reason: "not applicable to this subject" });
+			continue;
+		}
+		chain.push(provider);
+	}
+
+	return { chain, skipped };
+}
+
+/** Dot path lookup, e.g. pick("result.markdown") on a parsed JSON body. */
+export function pickPath(body: unknown, path: string): unknown {
+	let cursor: unknown = body;
+	for (const segment of path.split(".")) {
+		if (cursor === null || typeof cursor !== "object") return undefined;
+		cursor = (cursor as Record<string, unknown>)[segment];
+	}
+	return cursor;
+}