@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/ai/routes.ts

@@ -0,0 +1,359 @@
+/**
+ * AI Enrichment admin routes (/_emdash/api/plugins/coywolf-pack/ai/*).
+ * Everything that costs a model call is gated by its feature switch.
+ */
+import type { PluginContext } from "emdash";
+import { PluginRouteError, definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { ctxFeatures, isOn, requireFeature } from "../core/features.js";
+import { parseInput } from "../shared.js";
+import { type QueueJob, cleanText, DESCRIPTION_MAX, ALT_MAX, CAPTION_MAX } from "./logic.js";
+import { type ModelOption, PROVIDERS, chat, listModels } from "./providers.js";
+import {
+	type AiOptions,
+	type BulkState,
+	type EntryRecord,
+	type MediaRecord,
+	type UsageRow,
+	SETTINGS_SCHEMA,
+	bulkKey,
+	callsToday,
+	col,
+	enqueue,
+	entryKey,
+	lockHeld,
+	logUsage,
+	providerConfig,
+	publicSettings,
+	queueCounts,
+	readSettings,
+	takeCall,
+} from "./store.js";
+import { applyDescription, applyImageText, targetCollections, tick } from "./worker.js";
+
+const asCtx = (ctx: unknown) => ctx as PluginContext;
+/** Model lists per provider, per isolate (keyed to the saved key so a new key refetches). */
+const modelCache = new Map<string, { key: string; at: number; models: ModelOption[] }>();
+
+const settingsInput = z.object({
+	aiProvider: z.enum(["workers-ai", "anthropic", "openai", "gemini"]).optional(),
+	aiModel: z.string().max(200).optional(),
+	aiVisionModel: z.string().max(200).optional(),
+	/** A new key; omit to keep the saved one. */
+	aiApiKey: z.string().max(500).optional(),
+	clearApiKey: z.boolean().optional(),
+	aiMaxCallsPerDay: z.number().int().min(1).max(100000).optional(),
+	aiJobsPerTick: z.number().int().min(1).max(20).optional(),
+	aiCollections: z.string().max(2000).optional(),
+	aiDebounceMinutes: z.number().int().min(0).max(120).optional(),
+	aiDescriptionsMode: z.enum(["suggest", "apply"]).optional(),
+	aiImageMode: z.enum(["apply", "suggest"]).optional(),
+	aiImageCaption: z.boolean().optional(),
+	aiImageOverwrite: z.boolean().optional(),
+	aiImageInstructions: z.string().max(4000).optional(),
+});
+
+const entryRef = z.object({ collection: z.string().min(1).max(200), id: z.string().min(1).max(200) });
+const listInput = z.object({ cursor: z.string().max(2000).optional(), filter: z.string().max(40).optional() });
+
+async function featureForBulk(ctx: PluginContext, kind: BulkState["kind"]) {
+	const features = await ctxFeatures(ctx);
+	const on = kind === "media" ? isOn(features, "ai.imageText") : isOn(features, "ai.entities") || isOn(features, "ai.descriptions");
+	if (!on) throw PluginRouteError.notFound("Turn on the matching AI feature first (Plugins → Coywolf Pack).");
+}
+
+export function aiRoutes(options: AiOptions) {
+	return {
+		"ai/status": {
+			permission: "plugins:manage" as const,
+			handler: async (raw: unknown) => {
+				const ctx = asCtx(raw);
+				const settings = await readSettings(ctx, options);
+				const features = await ctxFeatures(ctx);
+				const [entriesBulk, mediaBulk] = await Promise.all([ctx.kv.get<BulkState>(bulkKey("entries")), ctx.kv.get<BulkState>(bulkKey("media"))]);
+				return {
+					settings: publicSettings(settings),
+					providers: PROVIDERS,
+					features: {
+						ai: isOn(features, "ai"),
+						entities: isOn(features, "ai.entities"),
+						descriptions: isOn(features, "ai.descriptions"),
+						imageText: isOn(features, "ai.imageText"),
+						entitiesStandalone: isOn(features, "ai.entitiesStandalone"),
+					},
+					queue: await queueCounts(ctx),
+					bulk: { entries: entriesBulk, media: mediaBulk },
+					callsToday: await callsToday(ctx),
+					running: await lockHeld(ctx),
+					collections: await targetCollections(ctx, settings).catch(() => []),
+				};
+			},
+		},
+
+		"ai/settings": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				const input = parseInput(settingsInput, ctx.input);
+				const { aiApiKey, clearApiKey, ...rest } = input;
+				for (const [key, value] of Object.entries(rest)) {
+					if (value !== undefined && key in SETTINGS_SCHEMA) await ctx.settings.set(key, typeof value === "string" ? value.trim() : value);
+				}
+				if (clearApiKey) await ctx.settings.delete("aiApiKey");
+				else if (aiApiKey?.trim()) await ctx.settings.set("aiApiKey", aiApiKey.trim());
+				ctx.log.info("AI settings saved", { keys: Object.keys(rest), apiKeyChanged: Boolean(clearApiKey || aiApiKey) });
+				return { settings: publicSettings(await readSettings(ctx, options)) };
+			},
+		}),
+
+		/** Models the saved key (or Workers AI) can use, for the settings page's pickers. No model call. */
+		"ai/models": {
+			permission: "plugins:manage" as const,
+			handler: async (raw: unknown) => {
+				const ctx = asCtx(raw);
+				const s = await readSettings(ctx, options);
+				if (s.provider !== "workers-ai" && !s.apiKey) return { provider: s.provider, models: [] as ModelOption[] };
+				const cached = modelCache.get(s.provider);
+				if (cached && cached.key === s.apiKey && Date.now() - cached.at < 10 * 60_000) return { provider: s.provider, models: cached.models };
+				try {
+					const cfg = await providerConfig(ctx, options, s, false);
+					const models = await listModels(cfg);
+					modelCache.set(s.provider, { key: s.apiKey, at: Date.now(), models });
+					return { provider: s.provider, models };
+				} catch (error) {
+					return { provider: s.provider, models: [] as ModelOption[], error: String((error as Error).message ?? error).slice(0, 200) };
+				}
+			},
+		},
+
+		/** One tiny real call with the saved settings. Counts toward the daily limit. */
+		"ai/test": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				await requireFeature(ctx, "ai");
+				const s = await readSettings(ctx, options);
+				if (!(await takeCall(ctx, s.maxCallsPerDay))) return { ok: false, error: "Today's call limit is reached." };
+				const cfg = await providerConfig(ctx, options, s, false);
+				const started = Date.now();
+				try {
+					const result = await chat(cfg, { system: "Reply with exactly: OK", user: "ping", maxTokens: 20 });
+					await logUsage(ctx, { feature: "test", provider: s.provider, model: cfg.model, inputTokens: result.inputTokens, outputTokens: result.outputTokens, ok: true });
+					return { ok: result.text.trim().length > 0, reply: cleanText(result.text, 100), provider: s.provider, model: cfg.model, ms: Date.now() - started };
+				} catch (error) {
+					const message = String((error as Error).message ?? error).slice(0, 300);
+					await logUsage(ctx, { feature: "test", provider: s.provider, model: cfg.model, inputTokens: 0, outputTokens: 0, ok: false, error: message });
+					return { ok: false, error: message, provider: s.provider, model: cfg.model };
+				}
+			},
+		}),
+
+		/** Start a bulk run. The cron tick turns it into queue jobs a page at a time. */
+		"ai/bulk": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const { kind, force } = parseInput(z.object({ kind: z.enum(["entries", "media"]), force: z.boolean().optional() }), (raw as { input: unknown }).input);
+				await featureForBulk(ctx, kind);
+				const s = await readSettings(ctx, options);
+				const state: BulkState = {
+					kind,
+					force: force ?? false,
+					collections: kind === "entries" ? await targetCollections(ctx, s) : [],
+					queued: 0,
+					skipped: 0,
+					started: new Date().toISOString(),
+				};
+				await ctx.kv.set(bulkKey(kind), state);
+				return { bulk: state };
+			},
+		}),
+
+		/** Stop a bulk run and drop its queued jobs. */
+		"ai/bulk/cancel": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const { kind } = parseInput(z.object({ kind: z.enum(["entries", "media"]) }), (raw as { input: unknown }).input);
+				await ctx.kv.delete(bulkKey(kind));
+				const queue = col<QueueJob>(ctx, "aiQueue");
+				let removed = 0;
+				for (let i = 0; i < 20; i++) {
+					const page = await queue.query({ where: { kind: kind === "media" ? "media" : "entry" }, limit: 100 });
+					if (!page.items.length) break;
+					removed += await queue.deleteMany(page.items.map((j) => j.id));
+				}
+				return { removed };
+			},
+		}),
+
+		/** Process one queued item now (for trying settings without waiting for the schedule). */
+		"ai/run": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				await requireFeature(ctx, "ai");
+				return tick(ctx, options, { maxJobs: 1, budgetMs: 20_000 });
+			},
+		}),
+
+		"ai/entries": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const { cursor, filter } = parseInput(listInput, (raw as { input: unknown }).input);
+				const where: Record<string, string> | undefined = filter === "suggested" ? { descriptionStatus: "suggested" } : filter === "error" ? { status: "error" } : undefined;
+				const page = await col<EntryRecord>(ctx, "aiEntries").query({ where, orderBy: { updated: "desc" }, limit: 50, cursor });
+				return { items: page.items.map((i) => i.data), cursor: page.cursor, hasMore: page.hasMore };
+			},
+		}),
+
+		"ai/entry/reanalyze": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const features = await ctxFeatures(ctx);
+				if (!isOn(features, "ai.entities") && !isOn(features, "ai.descriptions")) throw PluginRouteError.notFound("Turn on AI entities or descriptions first.");
+				const { collection, id } = parseInput(entryRef, (raw as { input: unknown }).input);
+				await enqueue(ctx, { kind: "entry", collection, entryId: id, due: Date.now(), force: true });
+				return { queued: true };
+			},
+		}),
+
+		"ai/description/apply": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				await requireFeature(ctx, "ai.descriptions");
+				const input = parseInput(entryRef.extend({ description: z.string().min(1).max(500), replace: z.boolean().optional() }), (raw as { input: unknown }).input);
+				const description = cleanText(input.description, DESCRIPTION_MAX * 2);
+				const applied = await applyDescription(ctx, input.collection, input.id, description, input.replace ?? false);
+				if (!applied) throw PluginRouteError.badRequest("This entry already has a meta description (or its collection has no SEO panel). Choose Replace to overwrite it.");
+				const records = col<EntryRecord>(ctx, "aiEntries");
+				const key = entryKey(input.collection, input.id);
+				const prev = await records.get(key);
+				if (prev) await records.put(key, { ...prev, description, descriptionStatus: "applied", updated: new Date().toISOString() });
+				return { applied: true };
+			},
+		}),
+
+		"ai/description/dismiss": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const { collection, id } = parseInput(entryRef, (raw as { input: unknown }).input);
+				const records = col<EntryRecord>(ctx, "aiEntries");
+				const prev = await records.get(entryKey(collection, id));
+				if (prev) await records.put(entryKey(collection, id), { ...prev, descriptionStatus: "dismissed", updated: new Date().toISOString() });
+				return { dismissed: true };
+			},
+		}),
+
+		"ai/media": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const { cursor, filter } = parseInput(listInput, (raw as { input: unknown }).input);
+				const where: Record<string, string> | undefined = filter && ["suggested", "applied", "skipped", "error"].includes(filter) ? { status: filter } : undefined;
+				const page = await col<MediaRecord>(ctx, "aiMedia").query({ where, orderBy: { updated: "desc" }, limit: 50, cursor });
+				return { items: page.items.map((i) => i.data), cursor: page.cursor, hasMore: page.hasMore };
+			},
+		}),
+
+		"ai/media/generate": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				await requireFeature(ctx, "ai.imageText");
+				const { mediaId } = parseInput(z.object({ mediaId: z.string().min(1).max(200) }), (raw as { input: unknown }).input);
+				await enqueue(ctx, { kind: "media", mediaId, due: Date.now(), force: true });
+				return { queued: true };
+			},
+		}),
+
+		"ai/media/apply": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				await requireFeature(ctx, "ai.imageText");
+				const input = parseInput(
+					z.object({ mediaId: z.string().min(1).max(200), alt: z.string().max(1000).optional(), caption: z.string().max(1000).optional(), replace: z.boolean().optional() }),
+					(raw as { input: unknown }).input,
+				);
+				const alt = cleanText(input.alt ?? "", ALT_MAX);
+				const caption = cleanText(input.caption ?? "", CAPTION_MAX);
+				const written = await applyImageText(ctx, input.mediaId, { alt, caption }, { caption: Boolean(caption), overwrite: input.replace ?? false });
+				const records = col<MediaRecord>(ctx, "aiMedia");
+				const prev = await records.get(input.mediaId);
+				if (prev && written.length) await records.put(input.mediaId, { ...prev, status: "applied", written, updated: new Date().toISOString() });
+				return { written };
+			},
+		}),
+
+		"ai/media/dismiss": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const { mediaId } = parseInput(z.object({ mediaId: z.string().min(1).max(200) }), (raw as { input: unknown }).input);
+				const records = col<MediaRecord>(ctx, "aiMedia");
+				const prev = await records.get(mediaId);
+				if (prev) await records.put(mediaId, { ...prev, status: "dismissed", updated: new Date().toISOString() });
+				return { dismissed: true };
+			},
+		}),
+
+		"ai/usage": {
+			permission: "plugins:manage" as const,
+			handler: async (raw: unknown) => {
+				const ctx = asCtx(raw);
+				const page = await col<UsageRow>(ctx, "aiUsage").query({ orderBy: { time: "desc" }, limit: 100 });
+				return { items: page.items.map((i) => i.data), callsToday: await callsToday(ctx) };
+			},
+		},
+
+		"ai/queue/clear": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (raw) => {
+				const ctx = asCtx(raw);
+				const queue = col<QueueJob>(ctx, "aiQueue");
+				let removed = 0;
+				for (let i = 0; i < 20; i++) {
+					const page = await queue.query({ limit: 100 });
+					if (!page.items.length) break;
+					removed += await queue.deleteMany(page.items.map((j) => j.id));
+				}
+				await ctx.kv.delete(bulkKey("entries"));
+				await ctx.kv.delete(bulkKey("media"));
+				return { removed };
+			},
+		}),
+	};
+}

package/src/ai/store.ts

@@ -0,0 +1,301 @@
+/**
+ * AI Enrichment state: settings, plugin-storage records, the job queue, the
+ * daily call counter, the usage log, and a cron lock.
+ *
+ * Storage collections (plugin storage, D1):
+ *   aiQueue   — pending jobs, id "entry:<collection>:<id>" or "media:<id>"
+ *   aiEntries — per-entry analysis: hash, entities, description suggestion
+ *   aiMedia   — per-image suggestion and what was written
+ *   aiUsage   — one row per model call (kept 30 days)
+ */
+import type { PluginContext, StorageCollection } from "emdash";
+
+import { workerEnv } from "../shared.js";
+import { type Entity, type ImageText, type QueueJob, dayKey, mergeJob, queueId } from "./logic.js";
+import { PROVIDERS, type ProviderConfig, type ProviderId } from "./providers.js";
+
+export interface AiOptions {
+	/** Workers AI binding name. Default "AI". */
+	binding?: string;
+	/** Cloudflare Images binding used to downscale large images before analysis. Default "IMAGES". */
+	images?: string;
+}
+
+export const STORAGE = {
+	aiQueue: { indexes: ["due", "kind"] },
+	aiEntries: { indexes: ["collection", "status", "descriptionStatus", "updated"] },
+	aiMedia: { indexes: ["status", "updated"] },
+	aiUsage: { indexes: ["time"] },
+};
+
+export const SETTINGS_SCHEMA = {
+	aiProvider: {
+		type: "select" as const,
+		label: "AI: provider",
+		description: "Workers AI runs on your Cloudflare account (needs the AI binding). The others need your own API key.",
+		options: PROVIDERS.map((p) => ({ value: p.id, label: p.label })),
+		default: "workers-ai",
+	},
+	aiModel: { type: "string" as const, label: "AI: text model", description: "Leave blank for the provider's default." },
+	aiVisionModel: { type: "string" as const, label: "AI: image model", description: "Must accept images. Leave blank for the provider's default." },
+	aiApiKey: { type: "secret" as const, label: "AI: API key", description: "For Anthropic, OpenAI, or Gemini. Stored encrypted." },
+	aiMaxCallsPerDay: { type: "number" as const, label: "AI: max model calls per day", min: 1, max: 100000, default: 200 },
+	aiJobsPerTick: { type: "number" as const, label: "AI: items per scheduled run", description: "Scheduled runs happen every two minutes, or with each cron tick if the site's cron runs less often.", min: 1, max: 20, default: 3 },
+	aiCollections: { type: "string" as const, label: "AI: collections", description: "Comma-separated collection slugs. Blank = every public collection." },
+	aiDebounceMinutes: { type: "number" as const, label: "AI: wait after a save (minutes)", min: 0, max: 120, default: 2 },
+	aiDescriptionsMode: {
+		type: "select" as const,
+		label: "AI: meta descriptions",
+		options: [
+			{ value: "suggest", label: "Suggest (review on the AI page)" },
+			{ value: "apply", label: "Fill empty descriptions automatically" },
+		],
+		default: "suggest",
+	},
+	aiImageMode: {
+		type: "select" as const,
+		label: "AI: image text",
+		options: [
+			{ value: "apply", label: "Fill empty alt text automatically" },
+			{ value: "suggest", label: "Suggest (review on the AI page)" },
+		],
+		default: "apply",
+	},
+	aiImageCaption: { type: "boolean" as const, label: "AI: also write captions", default: false },
+	aiImageOverwrite: { type: "boolean" as const, label: "AI: overwrite existing alt text and captions", default: false },
+	aiImageInstructions: { type: "string" as const, label: "AI: extra image instructions", multiline: true },
+};
+
+export interface AiSettings {
+	provider: ProviderId;
+	textModel: string;
+	visionModel: string;
+	apiKeySet: boolean;
+	maxCallsPerDay: number;
+	jobsPerTick: number;
+	collections: string[];
+	debounceMinutes: number;
+	descriptionsMode: "suggest" | "apply";
+	imageMode: "apply" | "suggest";
+	imageCaption: boolean;
+	imageOverwrite: boolean;
+	imageInstructions: string;
+	bindingAvailable: boolean;
+	imagesBindingAvailable: boolean;
+}
+
+type Ctx = Pick<PluginContext, "settings" | "storage" | "kv" | "log"> & Partial<Pick<PluginContext, "http">>;
+
+const clamp = (n: unknown, min: number, max: number, fallback: number) => {
+	const v = typeof n === "number" && Number.isFinite(n) ? n : fallback;
+	return Math.min(max, Math.max(min, Math.round(v)));
+};
+
+export async function bindings(options: AiOptions) {
+	const env = await workerEnv().catch(() => ({}) as Record<string, unknown>);
+	const ai = env[options.binding ?? "AI"] as ProviderConfig["binding"] | undefined;
+	const images = env[options.images ?? "IMAGES"] as ImagesBinding | undefined;
+	return { ai: ai && typeof ai.run === "function" ? ai : undefined, images: images && typeof images.input === "function" ? images : undefined };
+}
+
+export async function readSettings(ctx: Pick<PluginContext, "settings">, options: AiOptions): Promise<AiSettings & { apiKey: string }> {
+	const keys = Object.keys(SETTINGS_SCHEMA) as Array<keyof typeof SETTINGS_SCHEMA>;
+	const [{ ai, images }, values] = await Promise.all([
+		bindings(options),
+		Promise.all(keys.map((key) => ctx.settings.get<unknown>(key).catch(() => null))),
+	]);
+	const v = Object.fromEntries(keys.map((key, i) => [key, values[i]])) as Record<keyof typeof SETTINGS_SCHEMA, unknown>;
+	const str = (value: unknown) => (typeof value === "string" ? value.trim() : "");
+	const stored = str(v.aiProvider) as ProviderId;
+	const provider: ProviderId = PROVIDERS.some((p) => p.id === stored) ? stored : ai ? "workers-ai" : "anthropic";
+	const def = PROVIDERS.find((p) => p.id === provider)!;
+	const apiKey = str(v.aiApiKey);
+	return {
+		provider,
+		textModel: str(v.aiModel) || def.textModel,
+		visionModel: str(v.aiVisionModel) || def.visionModel,
+		apiKey,
+		apiKeySet: apiKey.length > 0,
+		maxCallsPerDay: clamp(v.aiMaxCallsPerDay, 1, 100000, 200),
+		jobsPerTick: clamp(v.aiJobsPerTick, 1, 20, 3),
+		collections: str(v.aiCollections)
+			.split(",")
+			.map((c) => c.trim())
+			.filter(Boolean),
+		debounceMinutes: clamp(v.aiDebounceMinutes, 0, 120, 2),
+		descriptionsMode: v.aiDescriptionsMode === "apply" ? "apply" : "suggest",
+		imageMode: v.aiImageMode === "suggest" ? "suggest" : "apply",
+		imageCaption: v.aiImageCaption === true,
+		imageOverwrite: v.aiImageOverwrite === true,
+		imageInstructions: typeof v.aiImageInstructions === "string" ? v.aiImageInstructions : "",
+		bindingAvailable: Boolean(ai),
+		imagesBindingAvailable: Boolean(images),
+	};
+}
+
+/** Settings safe to send to the admin (no key). */
+export function publicSettings(s: AiSettings & { apiKey: string }): AiSettings {
+	const { apiKey: _omit, ...rest } = s;
+	return rest;
+}
+
+export async function providerConfig(ctx: Ctx, options: AiOptions, s: AiSettings & { apiKey: string }, vision: boolean): Promise<ProviderConfig> {
+	const { ai } = await bindings(options);
+	return {
+		provider: s.provider,
+		model: vision ? s.visionModel : s.textModel,
+		apiKey: s.apiKey,
+		binding: ai,
+		fetch: (url, init) => (ctx.http ? ctx.http.fetch(url, init) : fetch(url, init)),
+	};
+}
+
+// ── Storage records ──────────────────────────────────────────────
+
+export interface EntryRecord {
+	collection: string;
+	entryId: string;
+	title: string;
+	hash: string;
+	status: "ok" | "error";
+	error: string;
+	entities: Entity[];
+	/** AI-written description and what happened to it. */
+	description: string;
+	descriptionStatus: "none" | "suggested" | "applied" | "dismissed";
+	updated: string;
+}
+
+export interface MediaRecord {
+	mediaId: string;
+	filename: string;
+	url: string;
+	suggestion: ImageText | null;
+	status: "suggested" | "applied" | "skipped" | "error" | "dismissed";
+	written: string[];
+	error: string;
+	updated: string;
+}
+
+export interface UsageRow {
+	time: string;
+	feature: "entities" | "descriptions" | "imageText" | "test";
+	provider: string;
+	model: string;
+	inputTokens: number;
+	outputTokens: number;
+	ok: boolean;
+	error?: string;
+	ref?: string;
+}
+
+export function col<T>(ctx: Pick<PluginContext, "storage">, name: keyof typeof STORAGE): StorageCollection<T> {
+	return (ctx.storage as Record<string, StorageCollection>)[name] as StorageCollection<T>;
+}
+
+export const entryKey = (collection: string, id: string) => `${collection}:${id}`;
+
+// ── Queue ────────────────────────────────────────────────────────
+
+export async function enqueue(ctx: Pick<PluginContext, "storage">, job: Omit<QueueJob, "attempts" | "enqueuedAt"> & Partial<QueueJob>): Promise<void> {
+	const queue = col<QueueJob>(ctx, "aiQueue");
+	const id = queueId(job);
+	const next: QueueJob = { attempts: 0, enqueuedAt: Date.now(), ...job };
+	await queue.put(id, mergeJob(await queue.get(id), next));
+}
+
+export async function queueCounts(ctx: Pick<PluginContext, "storage">) {
+	const queue = col<QueueJob>(ctx, "aiQueue");
+	const [entries, media] = await Promise.all([queue.count({ kind: "entry" }), queue.count({ kind: "media" })]);
+	return { entries, media };
+}
+
+// ── Daily call cap ───────────────────────────────────────────────
+
+const callsKey = (now = Date.now()) => `state:ai:calls:${dayKey(now)}`;
+
+export async function callsToday(ctx: Pick<PluginContext, "kv">): Promise<number> {
+	return (await ctx.kv.get<number>(callsKey())) ?? 0;
+}
+
+/** Count one model call against today's cap. Returns false (and counts nothing) when the cap is reached. */
+export async function takeCall(ctx: Pick<PluginContext, "kv">, max: number): Promise<boolean> {
+	const key = callsKey();
+	for (let i = 0; i < 5; i++) {
+		const current = await ctx.kv.getVersioned<number>(key);
+		const used = current?.value ?? 0;
+		if (used >= max) return false;
+		const result = await ctx.kv.compareAndSet(key, current?.revision ?? null, used + 1);
+		if (result.applied) return true;
+	}
+	return false;
+}
+
+export class DailyLimitError extends Error {
+	constructor() {
+		super("Today's AI call limit is reached. Work resumes tomorrow (UTC), or raise the limit on the AI page.");
+		this.name = "DailyLimitError";
+	}
+}
+
+// ── Usage log ────────────────────────────────────────────────────
+
+export async function logUsage(ctx: Pick<PluginContext, "storage">, row: Omit<UsageRow, "time">): Promise<void> {
+	const time = new Date().toISOString();
+	try {
+		await col<UsageRow>(ctx, "aiUsage").put(`${time}-${crypto.randomUUID().slice(0, 8)}`, { time, ...row });
+	} catch {
+		// The log is best effort.
+	}
+}
+
+/** Delete usage rows older than 30 days, a page at a time. */
+export async function pruneUsage(ctx: Pick<PluginContext, "storage">): Promise<void> {
+	const cutoff = new Date(Date.now() - 30 * 86_400_000).toISOString();
+	const usage = col<UsageRow>(ctx, "aiUsage");
+	const old = await usage.query({ where: { time: { lt: cutoff } }, limit: 200 });
+	if (old.items.length) await usage.deleteMany(old.items.map((i) => i.id));
+}
+
+// ── Lock ─────────────────────────────────────────────────────────
+
+const LOCK_KEY = "state:ai:lock";
+
+/** A soft lock so the cron tick and "Run now" don't process the queue concurrently. */
+export async function withLock<T>(ctx: Pick<PluginContext, "kv">, ttlMs: number, fn: () => Promise<T>): Promise<T | null> {
+	const now = Date.now();
+	const current = await ctx.kv.getVersioned<{ until: number; token: string }>(LOCK_KEY);
+	if (current?.value && current.value.until > now) return null;
+	const token = crypto.randomUUID();
+	const taken = await ctx.kv.compareAndSet(LOCK_KEY, current?.revision ?? null, { until: now + ttlMs, token });
+	if (!taken.applied) return null;
+	try {
+		return await fn();
+	} finally {
+		const mine = await ctx.kv.getVersioned<{ token: string }>(LOCK_KEY);
+		if (mine?.value?.token === token) await ctx.kv.compareAndDelete(LOCK_KEY, mine.revision).catch(() => undefined);
+	}
+}
+
+export async function lockHeld(ctx: Pick<PluginContext, "kv">): Promise<boolean> {
+	const current = await ctx.kv.get<{ until: number }>(LOCK_KEY);
+	return Boolean(current && current.until > Date.now());
+}
+
+// ── Bulk scan state ──────────────────────────────────────────────
+
+export interface BulkState {
+	kind: "entries" | "media";
+	force: boolean;
+	/** Collections still to scan (entries). */
+	collections: string[];
+	cursor?: string;
+	queued: number;
+	skipped: number;
+	started: string;
+	finished?: string;
+}
+
+export const bulkKey = (kind: BulkState["kind"]) => `state:ai:bulk:${kind}`;
+/** Epoch ms until which Wikidata asked to slow down (shared by every entry job, so one Retry-After throttles them all). */
+export const WIKIDATA_BUSY_KEY = "state:ai:wikidataBusyUntil";