@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/ai/pack.ts

@@ -0,0 +1,121 @@
+/**
+ * AI Enrichment module: Wikidata-grounded entities for Schema.org
+ * (about/mentions/sameAs), AI meta descriptions, and AI image text (alt text
+ * and captions). Saves and uploads only enqueue work; the cron tick does the
+ * model calls, within a daily call limit.
+ */
+import type { PluginContext } from "emdash";
+
+import { cachedCtxFeatures, ctxFeatures, isOn, registerFeatures } from "../core/features.js";
+import type { PackModule } from "../core/module.js";
+import { getEntryEntities } from "./entities.js";
+import { PROVIDER_HOSTS } from "./providers.js";
+import { aiRoutes } from "./routes.js";
+import { type AiOptions, STORAGE, col, enqueue, entryKey, readSettings, type EntryRecord } from "./store.js";
+import { WIKIDATA_HOST, WIKIDATA_QUERY_HOST } from "./wikidata.js";
+import { queueId } from "./logic.js";
+import { entryText, targetCollections, tick } from "./worker.js";
+
+export type { AiOptions } from "./store.js";
+export { getEntryEntities, type EntryEntities } from "./entities.js";
+
+const FEATURES = [
+	{
+		id: "ai",
+		label: "AI Enrichment",
+		description: "AI features powered by Workers AI or your own Anthropic, OpenAI, or Gemini key. Work runs in the background with a daily call limit.",
+		default: false,
+	},
+	{
+		id: "ai.entities",
+		label: "Entities for schema",
+		description: "Find the people, organizations, places, and things each page is about, verified against Wikidata, for Schema.org about/mentions.",
+		default: false,
+	},
+	{
+		id: "ai.entitiesStandalone",
+		label: "Output entities on their own",
+		description: "Add the entities to each page's JSON-LD by themselves. Only needed when Coywolf Schema isn't on.",
+		default: false,
+	},
+	{
+		id: "ai.descriptions",
+		label: "Meta descriptions",
+		description: "Write meta descriptions for published entries that don't have one, as suggestions or filled in automatically.",
+		default: false,
+	},
+	{
+		id: "ai.imageText",
+		label: "Image text",
+		description: "Write alt text (and optionally captions) for images on upload and in bulk. Text people wrote is kept.",
+		default: false,
+	},
+];
+registerFeatures(FEATURES);
+
+export const AI_TASK = "ai-queue";
+
+export function aiPack(options: AiOptions = {}): PackModule {
+	/** Queue an entry when its text changed since the last analysis (debounced). Never makes a model call. */
+	async function onContent(event: { content: Record<string, unknown>; collection: string }, ctx: PluginContext) {
+		const content = event.content;
+		const id = typeof content.id === "string" ? content.id : null;
+		// Only live content: skip unpublished entries and draft saves (autosaves) of published ones,
+		// whose pending draft differs from the live revision. Publishing the draft fires afterPublish.
+		if (!id || content.status !== "published") return;
+		if (typeof content.draftRevisionId === "string" && content.draftRevisionId && content.draftRevisionId !== content.liveRevisionId) return;
+		const features = await ctxFeatures(ctx);
+		if (!isOn(features, "ai.entities") && !isOn(features, "ai.descriptions")) return;
+		const s = await readSettings(ctx, options);
+		if (!(await targetCollections(ctx, s)).includes(event.collection)) return;
+		const data = (content.data && typeof content.data === "object" ? content.data : content) as Record<string, unknown>;
+		const t = await entryText(ctx, event.collection, data, s, features);
+		if (!t) return;
+		const prev = await col<EntryRecord>(ctx, "aiEntries").get(entryKey(event.collection, id));
+		if (prev?.status === "ok" && prev.hash === t.hash) return;
+		await enqueue(ctx, { kind: "entry", collection: event.collection, entryId: id, due: Date.now() + s.debounceMinutes * 60_000 });
+	}
+
+	return {
+		id: "ai",
+		label: "AI Enrichment",
+		features: FEATURES,
+		routes: aiRoutes(options),
+		hooks: {
+			"content:afterSave": onContent,
+			"content:afterPublish": onContent,
+			"content:afterRestore": onContent,
+			/** Forget a deleted (or trashed) entry: its analysis and any queued job. A restore queues it again. */
+			"content:afterDelete": async (event: { id: string; collection: string }, ctx: PluginContext) => {
+				await col<EntryRecord>(ctx, "aiEntries").delete(entryKey(event.collection, event.id));
+				await col(ctx, "aiQueue").delete(queueId({ kind: "entry", collection: event.collection, entryId: event.id }));
+			},
+			"media:afterUpload": async (event: { media: { id: string; mimeType: string } }, ctx: PluginContext) => {
+				const { id, mimeType } = event.media;
+				if (!mimeType?.startsWith("image/") || mimeType === "image/svg+xml") return;
+				await enqueue(ctx, { kind: "media", mediaId: id, due: Date.now() });
+			},
+			"page:metadata": async (event: { page: { content?: { collection: string; id: string }; canonical: string | null; url: string } }, ctx: PluginContext) => {
+				const ref = event.page.content;
+				if (!ref) return null;
+				// The Schema & Social graph already carries these on its Article/WebPage node.
+				if (isOn(await cachedCtxFeatures(ctx), "schema.graph")) return null;
+				const { about, mentions } = await getEntryEntities(ctx, ref.collection, ref.id);
+				if (!about.length && !mentions.length) return null;
+				const graph: Record<string, unknown> = { "@context": "https://schema.org", "@type": "WebPage", "@id": event.page.canonical ?? event.page.url };
+				if (about.length) graph.about = about;
+				if (mentions.length) graph.mentions = mentions;
+				return { kind: "jsonld", id: "coywolf-ai-entities", graph };
+			},
+		},
+		hookFeature: {
+			"media:afterUpload": "ai.imageText",
+			"page:metadata": "ai.entitiesStandalone",
+		},
+		tasks: [{ name: AI_TASK, schedule: "*/2 * * * *", handler: (ctx: PluginContext) => tick(ctx, options, { budgetMs: 8 * 60_000 }).then(() => undefined) }],
+		adminPages: [{ path: "/ai", label: "AI Enrichment", icon: "sparkle" }],
+		storage: STORAGE,
+		capabilities: ["network:request", "content:read", "content:write", "schema:read", "media:read", "media:bytes:read", "media:metadata:write"],
+		allowedHosts: [...PROVIDER_HOSTS, WIKIDATA_HOST, WIKIDATA_QUERY_HOST],
+	};
+}

package/src/ai/prompts.ts

@@ -0,0 +1,87 @@
+/**
+ * AI Enrichment prompts, ported from Coywolf SEO for WordPress
+ * (class-coywolf-seo-ai.php and class-coywolf-seo-image-ai.php).
+ */
+import type { Candidate, GroundedMention } from "./logic.js";
+import { DESCRIPTION_MAX } from "./logic.js";
+
+export const EXTRACT_SYSTEM =
+	"You extract named entities from an article for SEO schema markup. " +
+	"Respond with ONLY a JSON array — no prose, no code fences. Each element is an object with exactly these keys: " +
+	'"surface" (the entity exactly as written in the article), ' +
+	'"name" (the canonical, normalized name), ' +
+	'"type" (one of "Person", "Organization", "Place", "Thing"), ' +
+	'"description" (one short line stating what the entity is), ' +
+	'"primary" (true when the entity is a main subject of the article, false when it is mentioned in passing). ' +
+	"Rules: never output identifiers, QIDs, database IDs, or URLs of any kind. " +
+	"Only include real-world entities a reader could look up — people, organizations, places, products, published works, well-defined concepts. " +
+	"Skip the article author and the publishing website itself. At most 12 entities. If there are none, return [].";
+
+export const DISAMBIGUATE_SYSTEM =
+	"You match entities from an article to Wikidata items. " +
+	"Respond with ONLY a JSON object — no prose, no code fences — mapping each entity name to the QID string of the best-matching candidate, or null when no candidate clearly matches. " +
+	"Choose strictly among the provided candidates. Never produce a QID that is not listed. " +
+	"Use the article context, the entity type, and each candidate's Wikidata description to decide. If the choice is unclear, use null.";
+
+export const DESCRIBE_SYSTEM =
+	"You write the meta description for a web article. " +
+	"Respond with ONLY the meta description itself — plain text, a single line, no quotation marks around it, no markdown, no preamble, no explanation. " +
+	"It must be a faithful summary of the article content in one or two sentences, written for a search result snippet. " +
+	"No clickbait: no questions to the reader, no hype, no exclamation marks, no \"you won't believe\" teasers, and no promises the article doesn't keep. " +
+	`It must be STRICTLY UNDER ${DESCRIPTION_MAX} characters.`;
+
+export const IMAGE_SYSTEM =
+	"You write accessibility-first metadata for images in a website's media library, " +
+	"following WCAG-aligned guidance for alternative text, titles, and captions. " +
+	"You write for the people who depend on this text — screen reader and braille users, and anyone on a " +
+	"text-only or broken-image fallback — and never for search engines. " +
+	"You respond with raw JSON only: a single JSON object, no markdown fences, no commentary.";
+
+export function articlePrompt(title: string, content: string): string {
+	return `Title: ${title}\n\n${content}`;
+}
+
+export function disambiguatePrompt(ambiguous: GroundedMention[], title: string, content: string): string {
+	const lines = [`Article: ${title} — ${[...content].slice(0, 600).join("")}`, "", "Entities and their candidates:"];
+	for (const m of ambiguous) {
+		lines.push(`${m.name} (${m.type}${m.description ? ` — ${m.description}` : ""}):`);
+		for (const c of m.candidates as Candidate[]) lines.push(`  ${c.id}: ${c.label}${c.description ? ` — ${c.description}` : ""}`);
+	}
+	return lines.join("\n");
+}
+
+export function imagePrompt(opts: { filename: string; site: string; locale: string; extra?: string }): string {
+	let prompt =
+		"Analyze the image and write accessibility-first media library metadata for it, following the rules below. " +
+		"This metadata becomes the default for every future use of the file, and you are given no specific post context, so it must stand on its own.\n\n" +
+		"Respond with a JSON object:\n" +
+		'{"alt_text": string, "title": string, "caption": string}\n\n' +
+		"Write alt_text only when the image warrants it (an empty string for a purely decorative image); always provide a title and a caption.\n\n" +
+		"First, silently decide what kind of image this is, then write accordingly:\n" +
+		'- Decorative (a divider, texture, background flourish, or an icon that only repeats nearby text): return an empty alt_text. Do not invent text and do not write "decorative image". Still give it a useful title.\n' +
+		'- Functional (the image acts as a button or link): alt_text states the action or destination, not the artwork — a magnifying-glass search icon is "Search", not "Magnifying glass".\n' +
+		"- Text-bearing (a sign, quote card, screenshot, or graphic whose text is the point): transcribe the text verbatim in alt_text. If the visual design of the text is the point, describe that design as well.\n" +
+		"- Complex (a chart, infographic, diagram, or data-dense screenshot): alt_text is one sentence giving the takeaway.\n" +
+		"- Informative (any other image that carries meaning): alt_text describes what matters.\n\n" +
+		"alt_text — becomes the alt attribute:\n" +
+		"- Front-load the core subject and action, then add secondary details in descending importance, so a reader who stops after the first clause still has the essential picture.\n" +
+		"- Write full sentences in sentence case, ending with a period.\n" +
+		"- Default to one concise sentence (around 125 characters).\n" +
+		'- Never begin with "Image of", "Photo of", or "Graphic of". Name the medium only when it matters, e.g. "Watercolor painting of…" or "Screenshot of…".\n' +
+		'- Expand anything normally abbreviated: spell out units, measurements, and addresses ("5GB" becomes "5 gigabytes"; "123 Main St." becomes "123 Main Street"). Spell out acronyms unless this audience knows the acronym better.\n' +
+		"- Use proper typographic curly quotes and apostrophes (not straight ones) when quoting text that appears in the image.\n" +
+		"- Do not repeat what the caption says; alt_text and caption are read together, so write them as complements.\n\n" +
+		"title — an internal media library label:\n" +
+		'- A short, human-readable identifier of three to eight words in title case, e.g. "Barista Pouring Latte Art". Never a filename, never keywords, and never a copy of alt_text.\n\n' +
+		"caption — visible to everyone, shown as the figure caption:\n" +
+		"- One concise, informative sentence suitable to display beneath the image, phrased differently from alt_text.\n\n" +
+		`- Write every field in the language of locale "${opts.locale}".\n` +
+		"- Plain text only: no HTML and no markdown. Write for human readers; never write for SEO.\n";
+	const context: string[] = [];
+	if (opts.filename) context.push(`filename "${opts.filename}"`);
+	if (opts.site) context.push(`site "${opts.site}"`);
+	if (context.length) prompt += `\nContext that may help (ignore it if misleading): ${context.join(", ")}.`;
+	const extra = opts.extra?.trim();
+	if (extra) prompt += `\n\nAdditional site-specific instructions:\n${extra}`;
+	return prompt;
+}

package/src/ai/providers.ts

@@ -0,0 +1,276 @@
+/**
+ * Model providers for AI Enrichment: Workers AI (through the AI binding) or a
+ * bring-your-own key for Anthropic, OpenAI, or Google Gemini. One call shape
+ * for text and vision; usage is reported where the provider gives it.
+ * API keys are never logged or included in errors.
+ */
+
+export type ProviderId = "workers-ai" | "anthropic" | "openai" | "gemini";
+
+export const PROVIDERS: Array<{ id: ProviderId; label: string; textModel: string; visionModel: string }> = [
+	{ id: "workers-ai", label: "Cloudflare Workers AI", textModel: "@cf/meta/llama-4-scout-17b-16e-instruct", visionModel: "@cf/meta/llama-4-scout-17b-16e-instruct" },
+	// Checked 2026-10-03 against each provider's model docs: Claude Haiku 4.5 is only committed through
+	// Oct 15, 2026, so Sonnet 5.5 (through at least Sep 28, 2027) is the smallest Claude with a long runway;
+	// Gemini 2.5 is closed to new keys, Google recommends 3.8 Flash; GPT-6 Luna is OpenAI's efficient model.
+	{ id: "anthropic", label: "Anthropic (Claude)", textModel: "claude-sonnet-5-5", visionModel: "claude-sonnet-5-5" },
+	{ id: "openai", label: "OpenAI", textModel: "gpt-6-luna", visionModel: "gpt-6-luna" },
+	{ id: "gemini", label: "Google Gemini", textModel: "gemini-3.8-flash", visionModel: "gemini-3.8-flash" },
+];
+
+export const PROVIDER_HOSTS = ["api.anthropic.com", "api.openai.com", "generativelanguage.googleapis.com"];
+
+export interface ChatRequest {
+	system: string;
+	user: string;
+	image?: { mimeType: string; base64: string };
+	maxTokens: number;
+}
+
+export interface ChatResult {
+	/** Raw text, or an already-parsed object (Workers AI JSON mode). */
+	text: string;
+	inputTokens: number;
+	outputTokens: number;
+}
+
+export interface ProviderConfig {
+	provider: ProviderId;
+	model: string;
+	apiKey: string;
+	/** Workers AI binding (env.AI). */
+	binding?: { run(model: string, input: unknown, options?: unknown): Promise<unknown> };
+	/** fetch to use (the plugin's HTTP access when available). */
+	fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}
+
+const TIMEOUT_MS = 90_000;
+
+export class ProviderError extends Error {
+	constructor(
+		message: string,
+		readonly status?: number,
+	) {
+		super(message);
+		this.name = "ProviderError";
+	}
+}
+
+function redact(text: string, key: string): string {
+	let out = text;
+	if (key) out = out.split(key).join("[redacted]");
+	return out.replace(/\s+/g, " ").slice(0, 300);
+}
+
+async function httpError(response: Response, key: string, label: string): Promise<ProviderError> {
+	let detail = "";
+	try {
+		const body = (await response.json()) as { error?: { message?: string } | string; message?: string };
+		detail = typeof body.error === "string" ? body.error : (body.error?.message ?? body.message ?? "");
+	} catch {
+		detail = "";
+	}
+	return new ProviderError(`${label} returned HTTP ${response.status}${detail ? `: ${redact(detail, key)}` : ""}`, response.status);
+}
+
+async function postJson(cfg: ProviderConfig, url: string, headers: Record<string, string>, body: unknown, label: string): Promise<unknown> {
+	let response: Response;
+	try {
+		response = await cfg.fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json", ...headers },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(TIMEOUT_MS),
+		});
+	} catch (error) {
+		throw new ProviderError(`${label} request failed: ${redact(String((error as Error)?.message ?? error), cfg.apiKey)}`);
+	}
+	if (!response.ok) throw await httpError(response, cfg.apiKey, label);
+	return response.json();
+}
+
+async function workersAi(cfg: ProviderConfig, req: ChatRequest): Promise<ChatResult> {
+	if (!cfg.binding) throw new ProviderError("The Workers AI binding isn't configured. Add an \"ai\" binding to wrangler.jsonc (see docs/ai.md in the Coywolf Pack repository).");
+	const content = req.image
+		? [
+				{ type: "text", text: req.user },
+				{ type: "image_url", image_url: { url: `data:${req.image.mimeType};base64,${req.image.base64}` } },
+			]
+		: req.user;
+	let result: unknown;
+	try {
+		result = await cfg.binding.run(cfg.model, {
+			messages: [
+				{ role: "system", content: req.system },
+				{ role: "user", content },
+			],
+			max_tokens: req.maxTokens,
+		});
+	} catch (error) {
+		throw new ProviderError(`Workers AI: ${redact(String((error as Error)?.message ?? error), "")}`);
+	}
+	const r = result as { response?: unknown; usage?: { prompt_tokens?: number; completion_tokens?: number }; choices?: Array<{ message?: { content?: string } }> };
+	const raw = r.response ?? r.choices?.[0]?.message?.content ?? "";
+	return {
+		text: typeof raw === "string" ? raw : JSON.stringify(raw),
+		inputTokens: r.usage?.prompt_tokens ?? 0,
+		outputTokens: r.usage?.completion_tokens ?? 0,
+	};
+}
+
+async function anthropic(cfg: ProviderConfig, req: ChatRequest): Promise<ChatResult> {
+	const content: unknown[] = [];
+	if (req.image) content.push({ type: "image", source: { type: "base64", media_type: req.image.mimeType, data: req.image.base64 } });
+	content.push({ type: "text", text: req.user });
+	const data = (await postJson(
+		cfg,
+		"https://api.anthropic.com/v1/messages",
+		{ "x-api-key": cfg.apiKey, "anthropic-version": "2023-06-01" },
+		{ model: cfg.model, max_tokens: req.maxTokens, system: req.system, messages: [{ role: "user", content }] },
+		"Anthropic",
+	)) as { content?: Array<{ type?: string; text?: string }>; usage?: { input_tokens?: number; output_tokens?: number } };
+	return {
+		text: (data.content ?? []).filter((b) => b.type === "text").map((b) => b.text ?? "").join(""),
+		inputTokens: data.usage?.input_tokens ?? 0,
+		outputTokens: data.usage?.output_tokens ?? 0,
+	};
+}
+
+async function openai(cfg: ProviderConfig, req: ChatRequest): Promise<ChatResult> {
+	const user = req.image
+		? [
+				{ type: "text", text: req.user },
+				{ type: "image_url", image_url: { url: `data:${req.image.mimeType};base64,${req.image.base64}` } },
+			]
+		: req.user;
+	const body: Record<string, unknown> = {
+		model: cfg.model,
+		max_completion_tokens: req.maxTokens,
+		messages: [
+			{ role: "system", content: req.system },
+			{ role: "user", content: user },
+		],
+	};
+	const headers = { authorization: `Bearer ${cfg.apiKey}` };
+	let data: unknown;
+	try {
+		data = await postJson(cfg, "https://api.openai.com/v1/chat/completions", headers, body, "OpenAI");
+	} catch (error) {
+		// Some models reject max_completion_tokens; retry once with the legacy field.
+		if (!(error instanceof ProviderError) || error.status !== 400 || !error.message.includes("max_completion_tokens")) throw error;
+		const { max_completion_tokens, ...rest } = body;
+		data = await postJson(cfg, "https://api.openai.com/v1/chat/completions", headers, { ...rest, max_tokens: max_completion_tokens }, "OpenAI");
+	}
+	const d = data as { choices?: Array<{ message?: { content?: string } }>; usage?: { prompt_tokens?: number; completion_tokens?: number } };
+	return { text: d.choices?.[0]?.message?.content ?? "", inputTokens: d.usage?.prompt_tokens ?? 0, outputTokens: d.usage?.completion_tokens ?? 0 };
+}
+
+async function gemini(cfg: ProviderConfig, req: ChatRequest): Promise<ChatResult> {
+	const parts: unknown[] = [];
+	if (req.image) parts.push({ inline_data: { mime_type: req.image.mimeType, data: req.image.base64 } });
+	parts.push({ text: req.user });
+	const data = (await postJson(
+		cfg,
+		`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(cfg.model)}:generateContent`,
+		{ "x-goog-api-key": cfg.apiKey },
+		{
+			systemInstruction: { parts: [{ text: req.system }] },
+			contents: [{ role: "user", parts }],
+			// Thinking models spend output tokens before answering; leave room.
+			generationConfig: { maxOutputTokens: Math.max(4096, req.maxTokens) },
+		},
+		"Gemini",
+	)) as {
+		candidates?: Array<{ content?: { parts?: Array<{ text?: string; thought?: boolean }> } }>;
+		usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number };
+	};
+	const text = (data.candidates?.[0]?.content?.parts ?? [])
+		.filter((p) => typeof p.text === "string" && !p.thought)
+		.map((p) => p.text)
+		.join("");
+	return { text, inputTokens: data.usageMetadata?.promptTokenCount ?? 0, outputTokens: data.usageMetadata?.candidatesTokenCount ?? 0 };
+}
+
+/** Current hosted models may reason before answering, and that counts against the output limit; leave room. Billing is per token used. */
+const MIN_OUTPUT_TOKENS = 4096;
+
+export async function chat(cfg: ProviderConfig, input: ChatRequest): Promise<ChatResult> {
+	if (cfg.provider !== "workers-ai" && !cfg.apiKey) throw new ProviderError("Add an API key for the selected AI provider on the AI page.");
+	const req = cfg.provider === "workers-ai" ? input : { ...input, maxTokens: Math.max(MIN_OUTPUT_TOKENS, input.maxTokens) };
+	switch (cfg.provider) {
+		case "workers-ai":
+			return workersAi(cfg, req);
+		case "anthropic":
+			return anthropic(cfg, req);
+		case "openai":
+			return openai(cfg, req);
+		case "gemini":
+			return gemini(cfg, req);
+	}
+}
+
+// ── Model lists (for the settings page) ─────────────────────────
+
+export interface ModelOption {
+	id: string;
+	label: string;
+}
+
+/** Workers AI text-generation models that accept images (curated; the binding has no list call). */
+const WORKERS_AI_MODELS: ModelOption[] = [
+	{ id: "@cf/meta/llama-4-scout-17b-16e-instruct", label: "Llama 4 Scout 17B (text + images)" },
+	{ id: "@cf/mistralai/mistral-small-3.1-24b-instruct", label: "Mistral Small 3.1 24B (text + images)" },
+	{ id: "@cf/google/gemma-3-12b-it", label: "Gemma 3 12B (text + images)" },
+	{ id: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", label: "Llama 3.3 70B fast (text only)" },
+];
+
+/** OpenAI ids that aren't chat models (audio, images, embeddings, moderation, …). */
+const OPENAI_SKIP = /(audio|realtime|tts|transcribe|whisper|dall-e|image|embedding|moderation|search|computer-use|babbage|davinci|instruct)/i;
+
+/**
+ * Models the saved key can use, newest first where the provider says.
+ * The key is sent only to the provider and never returned or logged.
+ */
+export async function listModels(cfg: Pick<ProviderConfig, "provider" | "apiKey" | "fetch">): Promise<ModelOption[]> {
+	const get = async (url: string, headers: Record<string, string>) => {
+		const response = await cfg.fetch(url, { headers, signal: AbortSignal.timeout(15_000) });
+		if (!response.ok) throw new ProviderError(`The provider answered ${response.status} when listing models.`, response.status);
+		return (await response.json()) as Record<string, unknown>;
+	};
+	switch (cfg.provider) {
+		case "workers-ai":
+			return WORKERS_AI_MODELS;
+		case "anthropic": {
+			const out: ModelOption[] = [];
+			let after: string | undefined;
+			for (let page = 0; page < 5; page++) {
+				const body = await get(`https://api.anthropic.com/v1/models?limit=100${after ? `&after_id=${encodeURIComponent(after)}` : ""}`, {
+					"x-api-key": cfg.apiKey,
+					"anthropic-version": "2023-06-01",
+				});
+				const data = (body.data ?? []) as Array<{ id: string; display_name?: string }>;
+				for (const m of data) out.push({ id: m.id, label: m.display_name ? `${m.display_name} (${m.id})` : m.id });
+				if (!body.has_more || !data.length) break;
+				after = data[data.length - 1].id;
+			}
+			return out;
+		}
+		case "openai": {
+			const body = await get("https://api.openai.com/v1/models", { Authorization: `Bearer ${cfg.apiKey}` });
+			const data = (body.data ?? []) as Array<{ id: string; created?: number }>;
+			return data
+				.filter((m) => /^(gpt|o\d|chatgpt)/i.test(m.id) && !OPENAI_SKIP.test(m.id))
+				.sort((a, b) => (b.created ?? 0) - (a.created ?? 0))
+				.map((m) => ({ id: m.id, label: m.id }));
+		}
+		case "gemini": {
+			const body = await get("https://generativelanguage.googleapis.com/v1beta/models?pageSize=1000", { "x-goog-api-key": cfg.apiKey });
+			const models = (body.models ?? []) as Array<{ name: string; displayName?: string; supportedGenerationMethods?: string[] }>;
+			return models
+				.filter((m) => m.supportedGenerationMethods?.includes("generateContent") && /gemini/i.test(m.name))
+				.map((m) => {
+					const id = m.name.replace(/^models\//, "");
+					return { id, label: m.displayName ? `${m.displayName} (${id})` : id };
+				});
+		}
+	}
+}

package/src/ai/queue.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Unit tests for AI Enrichment queue batching.
+ * Run: node --test test/*.test.mjs (or node --test src/ai/*.test.ts)
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+// @ts-ignore -- Node runs the .ts source directly; tsc doesn't need to resolve it.
+import * as L from "./logic.ts";
+
+const logic = L as typeof import("./logic.js");
+type Job = import("./logic.js").QueueJob;
+
+const job = (id: string, due: number, kind: Job["kind"] = "entry"): { id: string; data: Job } => ({
+	id,
+	data: { kind, due, attempts: 0, enqueuedAt: 0, ...(kind === "media" ? { mediaId: id } : { collection: "posts", entryId: id }) },
+});
+
+test("planBatch takes due jobs in due order up to the per-tick limit", () => {
+	const jobs = [job("c", 300), job("a", 100), job("future", 10_000), job("b", 200)];
+	const out = logic.planBatch(jobs, { now: 1000, perTick: 2, remainingCalls: 100, callsPerJob: () => 3 });
+	assert.deepEqual(
+		out.map((j) => j.id),
+		["a", "b"],
+	);
+});
+
+test("planBatch respects the daily call budget and keeps each kind in order", () => {
+	const jobs = [job("entry1", 1), job("img", 2, "media"), job("entry2", 3)];
+	const cost = (j: Job) => (j.kind === "media" ? 1 : 3);
+	assert.deepEqual(
+		logic.planBatch(jobs, { now: 10, perTick: 10, remainingCalls: 4, callsPerJob: cost }).map((j) => j.id),
+		["entry1", "img"],
+	);
+	// Not enough budget for the first entry: no entry runs (entry2 doesn't jump the line), but the image can.
+	assert.deepEqual(
+		logic.planBatch(jobs, { now: 10, perTick: 10, remainingCalls: 2, callsPerJob: cost }).map((j) => j.id),
+		["img"],
+	);
+	assert.deepEqual(logic.planBatch(jobs, { now: 10, perTick: 10, remainingCalls: -5, callsPerJob: cost }), []);
+});
+
+test("deferJob pushes the job to Retry-After without an attempt, and gives up deferring after MAX_DEFERRALS in a row", () => {
+	const j = job("a", 0).data;
+	const once = logic.deferJob(j, 1_000, 30_000);
+	assert.deepEqual(once, { ...j, deferrals: 1, due: 31_000 });
+	assert.equal(once!.attempts, 0);
+	const tenth = logic.deferJob({ ...j, deferrals: logic.MAX_DEFERRALS - 1 }, 1_000, 30_000);
+	assert.equal(tenth?.deferrals, logic.MAX_DEFERRALS);
+	assert.equal(logic.deferJob({ ...j, deferrals: logic.MAX_DEFERRALS }, 1_000, 30_000), null, "the next one counts as a failed attempt");
+	assert.equal(logic.MAX_DEFERRALS, 10);
+});
+
+test("retryAt backs off and gives up after MAX_ATTEMPTS", () => {
+	const j = job("a", 0).data;
+	assert.equal(logic.retryAt({ ...j, attempts: 0 }, 0), 5 * 60_000);
+	assert.equal(logic.retryAt({ ...j, attempts: 1 }, 0), 20 * 60_000);
+	assert.equal(logic.retryAt({ ...j, attempts: logic.MAX_ATTEMPTS - 1 }, 0), null);
+});
+
+test("mergeJob debounces: later due wins, force sticks, attempts reset", () => {
+	const first: Job = { kind: "entry", collection: "posts", entryId: "1", due: 100, attempts: 2, enqueuedAt: 50, force: true };
+	const next: Job = { kind: "entry", collection: "posts", entryId: "1", due: 500, attempts: 0, enqueuedAt: 400 };
+	assert.deepEqual(logic.mergeJob(first, next), { ...next, force: true, enqueuedAt: 50, attempts: 0 });
+	assert.deepEqual(logic.mergeJob(null, next), next);
+});
+
+test("queueId and dayKey", () => {
+	assert.equal(logic.queueId({ kind: "entry", collection: "posts", entryId: "x" }), "entry:posts:x");
+	assert.equal(logic.queueId({ kind: "media", mediaId: "m" }), "media:m");
+	assert.equal(logic.dayKey(Date.UTC(2026, 9, 3, 23, 59)), "2026-10-03");
+});
+
+test("planBatch alternates kinds so a backlog of entries can't starve images", () => {
+	const jobs = [job("e1", 1), job("e2", 2), job("e3", 3), job("e4", 4), job("m1", 50, "media"), job("m2", 60, "media")];
+	const out = logic.planBatch(jobs, { now: 100, perTick: 4, remainingCalls: 100, callsPerJob: () => 1 });
+	assert.deepEqual(
+		out.map((j) => j.id),
+		["e1", "m1", "e2", "m2"],
+	);
+});
+
+test("planBatch stays within the subrequest budget; an expensive kind stops without blocking a cheap one", () => {
+	const jobs = [job("e1", 1), job("e2", 2), job("m1", 3, "media"), job("m2", 4, "media")];
+	const out = logic.planBatch(jobs, {
+		now: 100,
+		perTick: 10,
+		remainingCalls: 100,
+		callsPerJob: () => 1,
+		subrequests: 20,
+		subrequestsPerJob: (j: Job) => (j.kind === "entry" ? 16 : 1),
+	});
+	assert.deepEqual(
+		out.map((j) => j.id),
+		["e1", "m1", "m2"],
+	);
+});