pi-roundtable 0.24.2 → 0.25.0

package/src/core/agents/team-options.ts

@@ -50,10 +50,13 @@ export interface AgentTeamOptions
 	shellUser: string;
 	/** The scratch dir the agents' shell writes temporary files to. */
 	scratchDir?: string;
-	/** The prompt every persona shares, the assistant's included; each agent's starts with it. */
-	sharedPrompt: string;
+	/**
+	 * The prompt every persona shares, the assistant's included; each agent's starts with it. A
+	 * function is read before each turn, so an edit of the text applies from the next one.
+	 */
+	sharedPrompt: string | (() => string);
 	/** The shared prompt for speakers other than the owner, when `sharedPrompt` speaks to the owner. */
-	guestPrompt?: string;
+	guestPrompt?: string | (() => string);
 	/** The skill registry: what each agent carries. Absent when the skills addon is off. */
 	skills?: SkillRegistry;
 }

package/src/core/agents/team-selection.ts

@@ -0,0 +1,28 @@
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { SHELL_TOOLS } from "../modules/host-shell/shell-policy.ts";
+import type { TurnSelection } from "../sessions.ts";
+import { AGENT_TOOLS, MESSAGE_AGENT_TOOL } from "./agent-tools.ts";
+import type { AgentTeamOptions } from "./team-options.ts";
+
+/** The tools every agent turn runs with: the plugins', plus the shell and agent tools. */
+export function teamSelection(
+	options: Pick<AgentTeamOptions, "pluginSelection" | "pluginTools">,
+	scope?: AgentTurnScope,
+): TurnSelection {
+	const plugged = options.pluginSelection();
+	return {
+		id: "agent",
+		tools: [
+			...new Set([
+				...plugged.tools,
+				...SHELL_TOOLS,
+				// Group members hand off by mentioning each other, so a group seat has no message_agent.
+				...AGENT_TOOLS.filter(
+					(tool) => !(scope?.group && tool === MESSAGE_AGENT_TOOL),
+				),
+				...(options.pluginTools?.() ?? []),
+			]),
+		],
+		groups: plugged.groups,
+	};
+}

package/src/core/builtin/agent-server.ts

@@ -16,6 +16,7 @@ import type { ChannelKey } from "../domain/conversation.ts";
 import { ConfigError } from "../domain/errors.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import { ConfirmationJudge } from "../judging/confirmation-judge.ts";
+import type { Logger } from "../log.ts";
 import { AUTO_THINKING, formatModelRef, type ModelRef } from "../models.ts";
 import type { ErrorReporter } from "../ops/error-reporter.ts";
 import type { PluginContext, RoundtablePlugin } from "../plugin.ts";
@@ -25,6 +26,7 @@ import type { AgentSessionsSlot } from "../runtime/runtime-plugin.ts";
 import {
 	AGENTS,
 	BACKGROUND_TURNS,
+	PROMPTS,
 	RUNTIME,
 	SCHEDULES,
 	SKILLS,
@@ -126,11 +128,12 @@ export const AGENT_TEAM_SERVICE = "team";
 /** The agent tools and the agent's own prompt, which only agent sessions load. */
 export function agentSessionTools(
 	team: Pick<DiscordAgentTeam, "extension" | "systemPrompt">,
+	logger: Logger,
 ): SessionTool[] {
 	return [
 		agentOnly("agent-tools", (scope) => team.extension(scope)),
 		agentOnly("agent-prompt", (scope) =>
-			agentPromptExtension(() => team.systemPrompt(scope)),
+			agentPromptExtension(() => team.systemPrompt(scope), logger, scope.name),
 		),
 	];
 }
@@ -235,6 +238,27 @@ export function agentServerPlugin(
 				assistant: options.assistant,
 				logger,
 			});
+			// The owner edits the two prompts in the app when the prompts plugin is there; the text from the files is their default.
+			const documents = context.services.find(PROMPTS);
+			const shared = documents?.register({
+				id: "shared",
+				label: "Shared prompt",
+				description:
+					"The base every agent's prompt starts with, the main assistant's included.",
+				default: options.prompts.shared,
+			});
+			const guest =
+				documents && options.prompts.guest
+					? documents.register({
+							id: "guest",
+							label: "Guest prompt",
+							description:
+								"Used instead of the shared prompt when the person speaking is not the owner.",
+							default: options.prompts.guest,
+						})
+					: undefined;
+			const sharedPrompt = shared ? () => shared.text() : undefined;
+			const guestPrompt = guest ? () => guest.text() : undefined;
 			const built: DiscordAgentTeam = new DiscordAgentTeam({
 				guildId: teamId,
 				...(options.entryChannelId !== undefined
@@ -286,9 +310,9 @@ export function agentServerPlugin(
 				startTyping: (channel) => surfaces.startTyping(channel),
 				showStop: (channel) => surfaces.showStop(channel),
 				workDir: options.workDir,
-				sharedPrompt: options.prompts.shared,
-				...(options.prompts.guest
-					? { guestPrompt: options.prompts.guest }
+				sharedPrompt: sharedPrompt ?? options.prompts.shared,
+				...((guestPrompt ?? options.prompts.guest)
+					? { guestPrompt: guestPrompt ?? options.prompts.guest }
 					: {}),
 				...(skills ? { skills } : {}),
 				...(threads ? { threads } : {}),
@@ -396,7 +420,7 @@ export function agentServerPlugin(
 					options.avatarListener && options.avatarUrl
 						? [studio.route(options.avatarListener)]
 						: [],
-				sessionTools: agentSessionTools(built),
+				sessionTools: agentSessionTools(built, logger),
 				toolTiers: AGENT_TIERS,
 			};
 		},

package/src/core/builtin/prompts.ts

@@ -0,0 +1,40 @@
+import type { SQL } from "bun";
+import type { Logger } from "../log.ts";
+import { PgPromptDocuments } from "../modules/prompts/prompt-documents.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { PROMPTS } from "../services.ts";
+
+export interface PromptsOptions {
+	/** The guild whose overrides the documents keep, or the local team's id. */
+	guildId: string;
+}
+
+/**
+ * The prompt texts the owner edits in the app: the tables, the documents provided as `PROMPTS`
+ * (the agent server's and the plugins' registered during their setup), and one warning per
+ * document that differs from its file version, said once every plugin has registered.
+ */
+export function promptsPlugin(
+	options: PromptsOptions,
+	/** Opens the documents; a test hands stand-ins, so the plugin can be set up without a database. */
+	open: (
+		sql: SQL,
+		guildId: string,
+		logger: Logger,
+	) => Promise<PgPromptDocuments> = (sql, guildId, logger) =>
+		PgPromptDocuments.attach(sql, guildId, logger),
+): RoundtablePlugin {
+	let opened: { documents: PgPromptDocuments; logger: Logger } | undefined;
+	return {
+		name: "prompts",
+		migrations: PgPromptDocuments.migrations(),
+		provides: [PROMPTS],
+		preflight: () => opened?.documents.logOverrides(opened.logger),
+		setup: async ({ database, services, logger }) => {
+			const documents = await open(database(), options.guildId, logger);
+			opened = { documents, logger };
+			services.provide(PROMPTS, documents);
+			return {};
+		},
+	};
+}

package/src/core/builtin/skills.ts

@@ -70,11 +70,15 @@ export function skillsPlugin(
 			return {
 				sessionTools: [
 					agentOnly("skill-list", () => skillListExtension(built)),
-					agentOnly("skill-tools", () =>
-						skillToolsExtension(built, (name) => {
-							// The agent server is set up after this plugin and read when a session is built.
-							services.get(AGENTS).directory.activeAgent(name);
-						}),
+					agentOnly("skill-tools", (scope) =>
+						skillToolsExtension(
+							built,
+							(name) => {
+								// The agent server is set up after this plugin and read when a session is built.
+								services.get(AGENTS).directory.activeAgent(name);
+							},
+							scope.name,
+						),
 					),
 				],
 				agentSelection: () => ({

package/src/core/define-roundtable.ts

@@ -6,6 +6,7 @@ import { agentServerPlugin, LOCAL_TEAM_ID } from "./builtin/agent-server.ts";
 import { discordPlugin } from "./builtin/discord.ts";
 import { discordAdminPlugin } from "./builtin/discord-admin.ts";
 import { modulesPlugin, schedulerPlugin } from "./builtin/modules.ts";
+import { promptsPlugin } from "./builtin/prompts.ts";
 import { seedsPlugin } from "./builtin/seeds.ts";
 import { skillsPlugin } from "./builtin/skills.ts";
 import {
@@ -338,6 +339,8 @@ export async function defineRoundtable(
 			...(config.memory ? [memoryPlugin({ owner })] : []),
 			scheduleStorePlugin(),
 			precheckPlugin(),
+			// Before the agent server and the operator's plugins, which register the texts the owner edits.
+			promptsPlugin({ guildId: discord?.guild ?? LOCAL_TEAM_ID }),
 			// Before Discord, whose services hand out its instance, and the modules and agent server that use it.
 			threadsPlugin({ dataDir: config.dataDir }),
 			...(assembly ? [assembly.discord] : []),

package/src/core/i18n/agent-panel.ts

@@ -29,6 +29,8 @@ export function agentPanelEn(ctx: CatalogContext) {
 		agentDefaultNote:
 			"A changed prompt takes effect from this agent's next turn; the conversation history is kept.",
 		agentNotFound: "That agent was not found.",
+		agentSeededNotDeleted:
+			"This agent comes from the host's configuration, so it would return at the next start. Remove it from the configuration first.",
 		agentFollowAssistant: (value: string) =>
 			`Follow ${ctx.assistant} (${value})`,
 		agentModelModalTitle: (displayName: string) => `${displayName}'s model`,
@@ -76,6 +78,8 @@ export function agentPanelZhTW(
 		agentDefaultNote:
 			"提示詞改完，從這個 agent 的下一回合開始生效；對話紀錄保留。",
 		agentNotFound: "找不到這個 agent。",
+		agentSeededNotDeleted:
+			"這個 agent 來自主機的設定，刪除後下次啟動又會出現。請先從設定中移除它。",
 		agentFollowAssistant: (value: string) =>
 			`跟隨 ${ctx.assistant}（${value}）`,
 		agentModelModalTitle: (displayName: string) => `${displayName} 的模型`,

package/src/core/i18n/cards.ts

@@ -65,7 +65,7 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardRunLabel: "執行",
 		cardCancelLabel: "取消",
 		cardCopyLabel: "複製",
-		cardCopyGone: "這張卡片的文字已經不在了；請再請助理顯示一次。",
+		cardCopyGone: "這張卡片的文字已經不在了；請再請夥伴顯示一次。",
 		cardCopyFile: "文字比較長，所以用檔案附上。",
 		cardApprovalFooter: "你核准之前不會執行；準備好再回覆就好。",
 		cardQuestionFooter: "準備好再回答就好。",

package/src/core/modules/prompts/prompt-documents.ts

@@ -0,0 +1,425 @@
+import type { SQL } from "bun";
+import { isCheckDatabase } from "../../db/check-database.ts";
+import type { Migration } from "../../db/migrations.ts";
+import { AgentError } from "../../domain/errors.ts";
+import { type Logger, silentLogger } from "../../log.ts";
+import {
+	PromptHistory,
+	type PromptVersion,
+	promptHistoryMigration,
+} from "./prompt-history.ts";
+
+export type { PromptAction, PromptVersion } from "./prompt-history.ts";
+
+/** The most characters a document may have unless its spec says otherwise. */
+export const DEFAULT_DOCUMENT_CHARS = 20_000;
+
+const DOCUMENT_ID = /^[a-z0-9-]{1,32}$/;
+
+/** A prompt text the owner may edit, with the text from a file as its default. */
+export interface PromptDocumentSpec {
+	/** Lowercase letters, digits and hyphens; names the document for good. */
+	id: string;
+	/** What the owner sees it called. */
+	label: string;
+	/** One line on where the text is used. */
+	description?: string;
+	/**
+	 * The file version: the text read from a file or the configuration. A function is called each
+	 * time the document is read, so a default that follows a file is current.
+	 */
+	default: string | (() => string);
+	/** Default 20,000. */
+	maxChars?: number;
+}
+
+/** A registered document, read by whoever uses its text. */
+export interface PromptHandle {
+	readonly id: string;
+	/** The text in force now: the owner's override while one is set, else the file version. */
+	text(): string;
+}
+
+/** A document as the owner sees it. */
+export interface PromptDocumentView {
+	id: string;
+	label: string;
+	description?: string;
+	/** The text in force. */
+	text: string;
+	/** The file version. */
+	fileText: string;
+	/** An owner's override is set. */
+	overridden: boolean;
+	/** The override is set and its text is not the file version. */
+	differs: boolean;
+	override?: { by: string; at: Date };
+	maxChars: number;
+	/**
+	 * Why the file version cannot be read, when its `default` throws. The document is then listed
+	 * with an empty `fileText`, `differs` false and the override as `text` (empty with none), and
+	 * `set` and `revert` refuse it until the file reads again. One broken document never blanks
+	 * the others.
+	 */
+	broken?: string;
+}
+
+/**
+ * A change made from a text that is no longer the one in force: someone else changed the document
+ * meanwhile. Nothing was written; `current` is what is in force now.
+ */
+export class PromptConflictError extends Error {
+	override name = "PromptConflictError";
+	constructor(readonly current: PromptDocumentView) {
+		super(
+			`The prompt document "${current.id}" changed while it was being edited.`,
+		);
+	}
+}
+
+/**
+ * Prompt texts the owner edits outside the files: each has a file version, an optional override
+ * stored in the database, and a history. The override wins while it is set and is read at every
+ * turn, so a change applies from the next turn without a restart.
+ */
+export interface PromptDocuments {
+	/**
+	 * Registers a document during a plugin's setup. Throws AgentError for an unusable or repeated
+	 * id, and for a `default` that cannot be read now: the host does not start with it.
+	 */
+	register(spec: PromptDocumentSpec): PromptHandle;
+	/**
+	 * The text in force; throws AgentError for an unknown id, and for a document with no override
+	 * whose file version cannot be read (logged as an error naming the document).
+	 */
+	text(id: string): string;
+	/** Every document, in the order they were registered. */
+	list(): PromptDocumentView[];
+	/** One document, or undefined for an unknown id. */
+	get(id: string): PromptDocumentView | undefined;
+	/**
+	 * Sets the override. The text must have 1 to `maxChars` characters and differ from the text in
+	 * force; text equal to the file version reverts instead. Throws AgentError otherwise.
+	 *
+	 * `base` is the text the change was edited from. When it is given and is not the text in force
+	 * when the write comes up in the queue, nothing is written and PromptConflictError carries the
+	 * document as it is now.
+	 */
+	set(
+		id: string,
+		text: string,
+		by: string,
+		base?: string,
+	): Promise<PromptDocumentView>;
+	/**
+	 * Returns to the file version, dropping the override. Throws AgentError when none is set, and
+	 * PromptConflictError as `set` does when `base` is not the text in force.
+	 */
+	revert(id: string, by: string, base?: string): Promise<PromptDocumentView>;
+	/** The changes of one document, newest first. */
+	history(id: string, limit?: number): Promise<PromptVersion[]>;
+}
+
+interface OverrideRow {
+	name: string;
+	text: string;
+	by_name: string;
+	at: Date;
+}
+
+interface Override {
+	text: string;
+	by: string;
+	at: Date;
+}
+
+interface Registered {
+	spec: PromptDocumentSpec;
+}
+
+const fileText = (spec: PromptDocumentSpec): string =>
+	typeof spec.default === "function" ? spec.default() : spec.default;
+
+/** What reading a document's file version gave: its text, or why it could not be read. */
+type FileRead = { text: string } | { broken: string; error: unknown };
+
+const readFile = (spec: PromptDocumentSpec): FileRead => {
+	try {
+		return { text: fileText(spec) };
+	} catch (error) {
+		return {
+			broken: error instanceof Error ? error.message : String(error),
+			error,
+		};
+	}
+};
+
+/** The documents of one guild (or the local team), with their overrides in PostgreSQL. */
+export class PgPromptDocuments implements PromptDocuments {
+	readonly #sql: SQL;
+	readonly #guild: string;
+	readonly #history: PromptHistory;
+	readonly #logger: Logger;
+	readonly #documents = new Map<string, Registered>();
+	readonly #overrides = new Map<string, Override>();
+	/** The tail of the writes, which run one at a time so none reads an override another is about to change. */
+	#queue: Promise<unknown> = Promise.resolve();
+
+	private constructor(sql: SQL, guildId: string, logger: Logger) {
+		this.#sql = sql;
+		this.#guild = guildId;
+		this.#logger = logger;
+		this.#history = new PromptHistory(sql, guildId);
+	}
+
+	/** The overrides and the history, created beside the agent server's own tables. */
+	static migrations(): Migration[] {
+		return [
+			{
+				name: "prompt-overrides",
+				up: async (sql) => {
+					await sql`
+						CREATE TABLE IF NOT EXISTS prompt_overrides (
+							guild_id text NOT NULL,
+							name text NOT NULL,
+							text text NOT NULL,
+							by_name text NOT NULL,
+							at timestamptz NOT NULL DEFAULT now(),
+							PRIMARY KEY (guild_id, name)
+						)`;
+				},
+			},
+			promptHistoryMigration("prompt-history"),
+		];
+	}
+
+	/**
+	 * The documents over the host's migrated pool, holding the overrides of one guild. A file
+	 * version that cannot be read is logged to `logger` as an error naming the document.
+	 */
+	static async attach(
+		sql: SQL,
+		guildId: string,
+		logger: Logger = silentLogger(),
+	): Promise<PgPromptDocuments> {
+		const documents = new PgPromptDocuments(sql, guildId, logger);
+		// `Roundtable.check()` has no database to read the rows from: nothing is overridden.
+		if (!isCheckDatabase(sql)) await documents.#reload();
+		return documents;
+	}
+
+	async #reload(): Promise<void> {
+		const rows: OverrideRow[] = await this
+			.#sql`SELECT name, text, by_name, at FROM prompt_overrides WHERE guild_id = ${this.#guild}`;
+		this.#overrides.clear();
+		for (const row of rows)
+			this.#overrides.set(row.name, {
+				text: row.text,
+				by: row.by_name,
+				at: new Date(row.at),
+			});
+	}
+
+	#serial<T>(write: () => Promise<T>): Promise<T> {
+		const run = this.#queue.then(write);
+		this.#queue = run.catch(() => undefined);
+		return run;
+	}
+
+	register(spec: PromptDocumentSpec): PromptHandle {
+		if (!DOCUMENT_ID.test(spec.id))
+			throw new AgentError(
+				`"${spec.id}" is not a usable prompt document id: use 1 to 32 lowercase letters, digits and hyphens.`,
+			);
+		if (this.#documents.has(spec.id))
+			throw new AgentError(`A prompt document "${spec.id}" already exists.`);
+		if (!spec.label.trim())
+			throw new AgentError(`The prompt document "${spec.id}" needs a label.`);
+		// A default that cannot be read now stops the host here, not at the first turn that needs it.
+		const read = readFile(spec);
+		if ("broken" in read)
+			throw new AgentError(
+				`The prompt document "${spec.id}" has no readable file version: ${read.broken}`,
+			);
+		this.#documents.set(spec.id, { spec });
+		return { id: spec.id, text: () => this.text(spec.id) };
+	}
+
+	#registered(id: string): PromptDocumentSpec {
+		const found = this.#documents.get(id);
+		if (!found) throw new AgentError(`There is no prompt document "${id}".`);
+		return found.spec;
+	}
+
+	/** The file version, or an AgentError naming the document when it cannot be read; logged either way. */
+	#file(spec: PromptDocumentSpec): string {
+		const read = readFile(spec);
+		if (!("broken" in read)) return read.text;
+		this.#logUnreadable(spec, read.error);
+		throw new AgentError(
+			`The file version of the prompt document "${spec.id}" cannot be read: ${read.broken}`,
+		);
+	}
+
+	#logUnreadable(spec: PromptDocumentSpec, error: unknown): void {
+		this.#logger.error(
+			{ document: spec.id, err: error },
+			"the file version of a prompt document cannot be read",
+		);
+	}
+
+	text(id: string): string {
+		const spec = this.#registered(id);
+		return this.#overrides.get(id)?.text ?? this.#file(spec);
+	}
+
+	#view(spec: PromptDocumentSpec): PromptDocumentView {
+		const read = readFile(spec);
+		const override = this.#overrides.get(spec.id);
+		const common = {
+			id: spec.id,
+			label: spec.label,
+			...(spec.description ? { description: spec.description } : {}),
+			overridden: override !== undefined,
+			...(override ? { override: { by: override.by, at: override.at } } : {}),
+			maxChars: spec.maxChars ?? DEFAULT_DOCUMENT_CHARS,
+		};
+		if ("broken" in read) {
+			this.#logUnreadable(spec, read.error);
+			return {
+				...common,
+				text: override?.text ?? "",
+				fileText: "",
+				differs: false,
+				broken: read.broken,
+			};
+		}
+		return {
+			...common,
+			text: override?.text ?? read.text,
+			fileText: read.text,
+			differs: override !== undefined && override.text !== read.text,
+		};
+	}
+
+	list(): PromptDocumentView[] {
+		return [...this.#documents.values()].map(({ spec }) => this.#view(spec));
+	}
+
+	get(id: string): PromptDocumentView | undefined {
+		const found = this.#documents.get(id);
+		return found ? this.#view(found.spec) : undefined;
+	}
+
+	set(
+		id: string,
+		text: string,
+		by: string,
+		base?: string,
+	): Promise<PromptDocumentView> {
+		return this.#serial(async () => {
+			const spec = this.#registered(id);
+			const file = this.#file(spec);
+			const now = this.#overrides.get(id)?.text ?? file;
+			if (base !== undefined && base !== now)
+				throw new PromptConflictError(this.#view(spec));
+			const max = spec.maxChars ?? DEFAULT_DOCUMENT_CHARS;
+			if (!text.trim() || text.length > max)
+				throw new AgentError(
+					`A prompt document must have 1 to ${max} characters; this one has ${text.length}.`,
+				);
+			if (text === now)
+				throw new AgentError("The text is the one already in force.");
+			if (text === file) return this.#revert(id, spec, file, by);
+			const at = new Date();
+			await this.#sql.begin(async (tx) => {
+				await tx`
+					INSERT INTO prompt_overrides (guild_id, name, text, by_name, at)
+					VALUES (${this.#guild}, ${id}, ${text}, ${by}, ${at})
+					ON CONFLICT (guild_id, name) DO UPDATE
+					SET text = EXCLUDED.text, by_name = EXCLUDED.by_name, at = EXCLUDED.at`;
+				await this.#history.record(
+					"document",
+					id,
+					{ action: "set", text, previous: now, by },
+					tx,
+				);
+			});
+			// The cache follows the committed write.
+			this.#overrides.set(id, { text, by, at });
+			return this.#view(spec);
+		});
+	}
+
+	revert(id: string, by: string, base?: string): Promise<PromptDocumentView> {
+		return this.#serial(async () => {
+			const spec = this.#registered(id);
+			const file = this.#file(spec);
+			if (
+				base !== undefined &&
+				base !== (this.#overrides.get(id)?.text ?? file)
+			)
+				throw new PromptConflictError(this.#view(spec));
+			if (!this.#overrides.has(id))
+				throw new AgentError(
+					`"${id}" has no override; the file version is in force.`,
+				);
+			return this.#revert(id, spec, file, by);
+		});
+	}
+
+	async #revert(
+		id: string,
+		spec: PromptDocumentSpec,
+		file: string,
+		by: string,
+	): Promise<PromptDocumentView> {
+		const previous = this.#overrides.get(id)?.text ?? file;
+		await this.#sql.begin(async (tx) => {
+			await tx`DELETE FROM prompt_overrides WHERE guild_id = ${this.#guild} AND name = ${id}`;
+			await this.#history.record(
+				"document",
+				id,
+				{ action: "revert", text: file, previous, by },
+				tx,
+			);
+		});
+		this.#overrides.delete(id);
+		return this.#view(spec);
+	}
+
+	history(id: string, limit?: number): Promise<PromptVersion[]> {
+		this.#registered(id);
+		return this.#history.list("document", id, limit);
+	}
+
+	/**
+	 * Says which documents differ from their file versions, and which overrides name a document
+	 * nobody registers; the host calls it once every plugin has registered its own.
+	 */
+	logOverrides(logger: Logger): void {
+		for (const [id, override] of this.#overrides) {
+			const found = this.#documents.get(id);
+			if (!found) {
+				logger.warn(
+					{ document: id, by: override.by },
+					"a stored prompt override names a document no plugin registers; it is ignored",
+				);
+				continue;
+			}
+			const read = readFile(found.spec);
+			if ("broken" in read) {
+				logger.error(
+					{ document: id, err: read.error },
+					"the file version of a prompt document cannot be read",
+				);
+				continue;
+			}
+			if (override.text === read.text) continue;
+			logger.warn(
+				{ document: id, by: override.by, at: override.at.toISOString() },
+				"a prompt document differs from its file version: the owner's override is in force until it is reverted in the app",
+			);
+		}
+	}
+}