pi-roundtable 0.1.0

package/src/core/plugin.ts

@@ -0,0 +1,200 @@
+import type { SQL } from "bun";
+import type { AgentSeed } from "./agents/agent-store.ts";
+import type {
+	ChannelClaim,
+	ConversationPort,
+	QueuePort,
+} from "./contract/channels.ts";
+import type { InteractionContribution } from "./contract/discord.ts";
+import type { Providers } from "./contract/providers.ts";
+import type { Migration } from "./db/migrations.ts";
+import type { ToolContribution } from "./define.ts";
+import type { HoldCheck, HoldRule } from "./holds.ts";
+import type { HttpRoute } from "./http/listeners.ts";
+import type { Logger } from "./log.ts";
+import type { ComposedInteractions } from "./registry/interactions.ts";
+import type { CoreAccess, CoreRegistry } from "./services.ts";
+import type {
+	AgentTurnScope,
+	ChannelKey,
+	SessionPlan,
+	SessionTool,
+	ToolSelection,
+} from "./sessions.ts";
+import type { Speaker } from "./speakers.ts";
+import type { ToolTiers } from "./tool-tiers.ts";
+
+/**
+ * A long-lived part of a plugin. Services start in registration order and stop in reverse,
+ * so one registered earlier outlives those registered after it.
+ */
+export interface Service {
+	name: string;
+	start?(): Promise<void> | void;
+	stop?(): Promise<void> | void;
+	/** Work still running or waiting, one entry each; the shutdown drain waits until every list is empty. */
+	busy?(): string[];
+}
+
+/** How the agent server's startup ended. */
+export type AgentServerOutcome = "ready" | "failed";
+
+/** One agent turn, as a handler hears of it. */
+export interface TurnEvent {
+	agent: string;
+	/** The channel the turn runs in: the agent's own, or a group's. */
+	channel: ChannelKey;
+	/** Who the turn is for. */
+	speaker: Speaker | undefined;
+	/** The group, for a member's turn in one. */
+	group?: string;
+}
+
+/** How a turn ended. */
+export interface TurnEndEvent extends TurnEvent {
+	result: "ok" | "failed" | "stopped";
+}
+
+/** What a plugin may react to; a handler that throws is logged and never stops the others. */
+export interface EventHandlers {
+	/** Once the agent server has started, or failed to; the rest of the process runs either way. */
+	agentServer?(outcome: AgentServerOutcome): Promise<void> | void;
+	/** An agent's turn began. */
+	turnStarted?(turn: TurnEvent): Promise<void> | void;
+	/** An agent's turn ended, however it ended. */
+	turnEnded?(turn: TurnEndEvent): Promise<void> | void;
+	/** The team changed: an agent or group was created, edited, arranged, archived, or started over. */
+	changed?(): Promise<void> | void;
+	/** The shutdown drain ended, before any service stops; `left` is the work it gave up on. */
+	shutdown?(left: readonly string[]): Promise<void> | void;
+}
+
+/** What the core reports to the plugins' handlers. */
+export interface EventSink {
+	turnStarted(turn: TurnEvent): void;
+	turnEnded(turn: TurnEndEvent): void;
+	changed(): void;
+}
+
+/** What a prompt section is built for: one agent's turn. */
+export interface PromptTurn {
+	agent: { name: string; displayName: string };
+	/** Who the turn is for; undefined between turns. */
+	speaker: Speaker | undefined;
+	scope: AgentTurnScope;
+}
+
+/** A section a plugin adds to every agent turn's system prompt. */
+export interface PromptSection {
+	name: string;
+	/** The section's text for the turn, or undefined to add nothing. */
+	build(turn: PromptTurn): string | undefined;
+}
+
+/** What a plugin adds to the process; a plugin that adds nothing is refused. */
+export interface Contribution {
+	services?: Service[];
+	events?: EventHandlers;
+	/** Modules that answer Discord interactions, with their subcommands under the root command. */
+	interactions?: InteractionContribution[];
+	/** Handlers on the host's HTTP listeners. */
+	http?: HttpRoute[];
+	/** Rules deciding which tool calls wait for the owner's approval, asked in contribution order. */
+	holdRules?: readonly HoldRule[];
+	/** Pi packages every conversation session loads, in contribution order. */
+	piPackages?: readonly string[];
+	/** Extensions of every conversation session, placed by phase around the core's own. */
+	sessionTools?: readonly SessionTool[];
+	/** The channels whose conversations the plugin owns. */
+	channels?: readonly ChannelClaim[];
+	/** Lines the agent server's dashboard shows under its title, such as links, in contribution order. */
+	dashboard?: readonly string[];
+	/** Tools the plugin adds, each with the lowest tier that may use it; built with `defineTool`. */
+	tools?: readonly ToolContribution[];
+	/** Agents created on the first start; one already stored is never overwritten. */
+	seeds?: readonly AgentSeed[];
+	/** Sections added to every agent turn's system prompt, in contribution order. */
+	prompt?: readonly PromptSection[];
+	/**
+	 * Tools and tool groups every agent turn carries besides its own, read before each turn so a
+	 * set that changes while the process runs, such as connected servers, stays current.
+	 */
+	agentSelection?: () => ToolSelection;
+}
+
+/** The parts a contribution may have; any other key is a mistake the host names. */
+export const CONTRIBUTION_KEYS = [
+	"services",
+	"events",
+	"interactions",
+	"http",
+	"holdRules",
+	"piPackages",
+	"sessionTools",
+	"channels",
+	"dashboard",
+	"tools",
+	"seeds",
+	"prompt",
+	"agentSelection",
+] as const satisfies readonly (keyof Contribution)[];
+
+/** The session parts the host links from every plugin's contributions once all are set up. */
+export interface LinkedSessions {
+	/** Every contributed hold rule, asked in contribution order until one describes the call. */
+	holds: HoldCheck;
+	/** Every contributed Pi package in contribution order, each once. */
+	piPackages: readonly string[];
+	plan: SessionPlan;
+	/** The agents every plugin seeds, in contribution order. */
+	seeds: readonly AgentSeed[];
+	/** Every plugin's prompt sections, in contribution order. */
+	prompt: readonly PromptSection[];
+	/** The tools plugins defined for agents, by name. */
+	agentTools: readonly string[];
+	/** Every plugin's agent selection merged, read before each agent turn. */
+	agentSelection(): ToolSelection;
+}
+
+/** What the host gives every plugin. */
+export interface PluginContext {
+	logger: Logger;
+	/** The linked session parts; throws NotLinkedError when called during setup. */
+	sessions(): LinkedSessions;
+	/** The one channel queue every conversation and channel operation shares. */
+	queue: QueuePort;
+	/** What each tool needs; plugin tools are added when the host links, so ask at use time. */
+	toolTiers: ToolTiers;
+	/** Where the core reports turns and team changes, for every plugin's handlers. */
+	events: EventSink;
+	/** The claimed channels' conversations; calls during setup throw NotLinkedError. */
+	conversations: ConversationPort;
+	/** The host's one connection pool, migrated before any setup; throws PluginError without a database. */
+	database(): SQL;
+	/** What the built-in plugins provide, for the plugins registered after them; throws PluginError until provided. */
+	core: CoreAccess & { provide: CoreRegistry["provide"] };
+	/** Each provider slot, from the plugin that fills it or the core's default. */
+	providers: Providers;
+	/** Every plugin's dashboard lines, in contribution order; throws NotLinkedError during setup. */
+	dashboard(): readonly string[];
+}
+
+export interface RoundtablePlugin {
+	name: string;
+	/** The plugin's tables; the host runs every plugin's, in registration order, before any setup. */
+	migrations?: readonly Migration[];
+	/** The provider slots the plugin fills, resolved before any setup; two plugins cannot fill one slot. */
+	providers?: Partial<Providers>;
+	setup(context: PluginContext): Promise<Contribution> | Contribution;
+	/**
+	 * Runs once every plugin is set up and linked, before the commands are handed over or any
+	 * service starts; a failure stops the boot, so a broken setup never reaches Discord.
+	 */
+	preflight?(): Promise<void> | void;
+	/** Receives the composed slash commands before any service starts, since Discord registers them as it connects. */
+	useCommands?(composed: ComposedInteractions): void;
+	/** Starts the agent server, in the background once every service has started; only one plugin has it. */
+	agentServer?(): Promise<void>;
+	/** Stops a running turn of a channel the plugin's conversations serve; true when one was running. */
+	stopTurn?(channel: ChannelKey): boolean;
+}

package/src/core/presentation/card-cadence.ts

@@ -0,0 +1,41 @@
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { Expression } from "../domain/expression.ts";
+
+/** A channel quiet this long starts a new conversation, whose first reply shows a card. */
+export const CONVERSATION_GAP_MS = 30 * 60_000;
+
+/**
+ * Decides which replies carry a card: one that opens a conversation or changes its tone.
+ * Kept in memory; after a restart every channel's next reply opens a conversation.
+ */
+export class CardCadence {
+	readonly #channels = new Map<
+		ChannelKey,
+		{ lastReplyAt: number; lastCard: Expression | undefined }
+	>();
+
+	/** Records a reply about to be posted and says whether it shows a card. */
+	shows(
+		channel: ChannelKey,
+		expression: Expression,
+		failed: boolean,
+		now = Date.now(),
+	): boolean {
+		const state = this.#channels.get(channel);
+		const card =
+			failed ||
+			!state ||
+			now - state.lastReplyAt >= CONVERSATION_GAP_MS ||
+			(expression !== "neutral" && expression !== state.lastCard);
+		this.#channels.set(channel, {
+			lastReplyAt: now,
+			lastCard: card ? expression : state?.lastCard,
+		});
+		return card;
+	}
+
+	/** The channel's next reply opens a conversation again. */
+	forget(channel: ChannelKey): void {
+		this.#channels.delete(channel);
+	}
+}

package/src/core/presentation/headline.ts

@@ -0,0 +1,34 @@
+const MAX_LENGTH = 80;
+// The card font has no emoji glyphs, so the card would draw each as a code-point box.
+const EMOJI =
+	/\p{Extended_Pictographic}|[\u{1F1E6}-\u{1F1FF}\u{1F3FB}-\u{1F3FF}]|\u{FE0F}|\u{200D}|\u{20E3}/gu;
+
+function stripMarkdown(line: string): string {
+	return line
+		.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+		.replace(/<(https?:\/\/[^>]+)>/g, "$1")
+		.replace(/^\s{0,3}(#{1,6}\s+|>\s?|[-*+]\s+|\d+[.)]\s+)/, "")
+		.replace(/(\*\*|__|~~|`)/g, "")
+		.replace(/(^|\s)[*_](\S[^*_]*)[*_](?=\s|$|[，。！？,.!?])/g, "$1$2")
+		.replace(EMOJI, "")
+		.replace(/\s{2,}/g, " ")
+		.trim();
+}
+
+/** The reply's first sentence as plain text without emoji, at most 80 characters. */
+export function headline(text: string): string {
+	const withoutCode = text.replace(/```[\s\S]*?(```|$)/g, "\n");
+	const firstLine = withoutCode
+		.split("\n")
+		.map(stripMarkdown)
+		.find((line) => line.length > 0);
+	if (!firstLine) return "";
+
+	const sentence =
+		firstLine.match(/^.*?(?:[。！？!?]|\.(?=\s|$))/)?.[0] ?? firstLine;
+	const characters = Array.from(sentence.trim());
+	return characters.length <= MAX_LENGTH
+		? characters.join("")
+		: `${characters.slice(0, MAX_LENGTH - 1).join("")}…`;
+}

package/src/core/presentation/presentation.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from "bun:test";
+import { CardCadence, CONVERSATION_GAP_MS } from "./card-cadence.ts";
+import { headline } from "./headline.ts";
+import { quietLinks } from "./quiet-links.ts";
+import { DISCORD_MESSAGE_LIMIT, splitReply } from "./reply-splitter.ts";
+import { THINKING_LIMIT, thinkingLine } from "./thinking-line.ts";
+
+describe("headline", () => {
+	test("takes the first sentence", () => {
+		expect(headline("Today is a nice day。Let us go for a walk！")).toBe(
+			"Today is a nice day。",
+		);
+		expect(headline("Bun 1.4.2 is out. It fixes a lot.")).toBe(
+			"Bun 1.4.2 is out.",
+		);
+	});
+
+	test("does not stop at a decimal point", () => {
+		expect(headline("Version 1.4.2 ships today")).toBe(
+			"Version 1.4.2 ships today",
+		);
+	});
+
+	test("strips markdown and skips code", () => {
+		expect(
+			headline(
+				"```ts\nconst x = 1;\n```\n## **Key point**：see [this post](https://x.y)",
+			),
+		).toBe("Key point：see this post");
+		expect(headline("- `bun` is fast")).toBe("bun is fast");
+	});
+
+	test("truncates to 80 characters", () => {
+		const result = headline("é".repeat(120));
+		expect(Array.from(result)).toHaveLength(80);
+		expect(result.endsWith("…")).toBe(true);
+	});
+
+	test("emoji are left out, since the card font cannot draw them", () => {
+		expect(headline("Schedule test OK，get some water 💧")).toBe(
+			"Schedule test OK，get some water",
+		);
+		expect(headline("🎉 Congrats 👍🏽 done 🇹🇼！")).toBe("Congrats done ！");
+		expect(headline("👨‍👩‍👧 family❤️ all good")).toBe("family all good");
+		expect(headline("💧")).toBe("");
+	});
+
+	test("empty text gives an empty headline", () => {
+		expect(headline("\n\n")).toBe("");
+	});
+});
+
+describe("splitReply", () => {
+	test("short text stays one message", () => {
+		expect(splitReply("hello\n\nworld")).toEqual(["hello\n\nworld"]);
+	});
+
+	test("splits on paragraph boundaries within the limit", () => {
+		const [a, b, c] = ["a".repeat(900), "b".repeat(900), "c".repeat(900)];
+		expect(splitReply(`${a}\n\n${b}\n\n${c}`)).toEqual([`${a}\n\n${b}`, c]);
+	});
+
+	test("keeps a code block with blank lines intact", () => {
+		const code = "```ts\nconst a = 1;\n\nconst b = 2;\n```";
+		const text = `${"x".repeat(1980)}\n\n${code}`;
+		expect(splitReply(text)).toEqual(["x".repeat(1980), code]);
+	});
+
+	test("a long code block becomes several complete code blocks", () => {
+		const body = Array.from(
+			{ length: 200 },
+			(_, i) => `line ${i} ${"-".repeat(20)}`,
+		).join("\n");
+		const chunks = splitReply(`\`\`\`ts\n${body}\n\`\`\``);
+		expect(chunks.length).toBeGreaterThan(1);
+		for (const chunk of chunks) {
+			expect(chunk.length).toBeLessThanOrEqual(2000);
+			expect(chunk.startsWith("```ts\n")).toBe(true);
+			expect(chunk.endsWith("\n```")).toBe(true);
+		}
+		const rejoined = chunks.map((c) => c.slice(6, -4)).join("\n");
+		expect(rejoined).toBe(body);
+	});
+
+	test("one overlong line is split by characters", () => {
+		const chunks = splitReply("é".repeat(4500));
+		expect(chunks.map((c) => c.length)).toEqual([2000, 2000, 500]);
+	});
+
+	test("every chunk respects the limit", () => {
+		const text = Array.from(
+			{ length: 50 },
+			(_, i) => `Paragraph ${i} ${"é".repeat(i * 10)}`,
+		).join("\n\n");
+		const chunks = splitReply(text);
+		expect(chunks.every((c) => c.length <= 2000)).toBe(true);
+		expect(chunks.join("\n\n")).toBe(text);
+	});
+});
+
+describe("quietLinks", () => {
+	test("wraps cited links and keeps sentence punctuation outside", () => {
+		expect(
+			quietLinks("Source：https://example.com/a?b=1。Also https://x.org/p."),
+		).toBe("Source：<https://example.com/a?b=1>。Also <https://x.org/p>.");
+	});
+
+	test("GIF and video links keep their preview", () => {
+		const text =
+			"https://giphy.com/gifs/clap\nhttps://www.youtube.com/watch?v=abc";
+		expect(quietLinks(text)).toBe(text);
+	});
+
+	test("markdown links and already wrapped links", () => {
+		expect(
+			quietLinks("[review](https://example.com/r) and <https://a.io>"),
+		).toBe("[review](<https://example.com/r>) and <https://a.io>");
+	});
+});
+
+describe("thinkingLine", () => {
+	test("each line becomes small grey text and blank lines are dropped", () => {
+		expect(thinkingLine("  check the date\n\nthen answer  ")).toBe(
+			"-# check the date\n-# then answer",
+		);
+		expect(thinkingLine("   ")).toBeUndefined();
+	});
+
+	test("long thinking is cut and stays within one message", () => {
+		const line = thinkingLine("é".repeat(THINKING_LIMIT + 50));
+		expect(line?.endsWith("…")).toBe(true);
+		expect(line?.length).toBeLessThanOrEqual(DISCORD_MESSAGE_LIMIT);
+	});
+});
+
+describe("card cadence", () => {
+	const at = (minutes: number) => minutes * 60_000;
+
+	test("a conversation's first reply shows a card; the same tone does not repeat it", () => {
+		const cadence = new CardCadence();
+		expect(cadence.shows("discord:1", "neutral", false, at(0))).toBe(true);
+		expect(cadence.shows("discord:1", "neutral", false, at(1))).toBe(false);
+		expect(cadence.shows("discord:1", "happy", false, at(2))).toBe(true);
+		expect(cadence.shows("discord:1", "happy", false, at(3))).toBe(false);
+		expect(cadence.shows("discord:1", "neutral", false, at(4))).toBe(false);
+		expect(cadence.shows("discord:1", "thinking", false, at(5))).toBe(true);
+	});
+
+	test("a quiet channel opens a new conversation", () => {
+		const cadence = new CardCadence();
+		cadence.shows("discord:1", "neutral", false, 0);
+		expect(
+			cadence.shows("discord:1", "neutral", false, CONVERSATION_GAP_MS - 1),
+		).toBe(false);
+		expect(
+			cadence.shows("discord:1", "neutral", false, 2 * CONVERSATION_GAP_MS - 1),
+		).toBe(true);
+	});
+
+	test("a failure always shows its card; channels are independent", () => {
+		const cadence = new CardCadence();
+		cadence.shows("discord:1", "apologetic", true, at(0));
+		expect(cadence.shows("discord:1", "apologetic", true, at(1))).toBe(true);
+		expect(cadence.shows("discord:2", "neutral", false, at(1))).toBe(true);
+	});
+});

package/src/core/presentation/quiet-links.ts

@@ -0,0 +1,36 @@
+/** Links whose preview is the point: a GIF or a video shows inline. */
+const PREVIEWED_HOSTS = [
+	"giphy.com",
+	"media.giphy.com",
+	"tenor.com",
+	"youtube.com",
+	"www.youtube.com",
+	"youtu.be",
+];
+
+const URL_CHARS = "[A-Za-z0-9\\-._~:/?#\\[\\]@!$&'*+,;=%]+";
+const BARE_URL = new RegExp(`(^|[^<(])(https?://${URL_CHARS})`, "g");
+const MARKDOWN_URL = new RegExp(`\\]\\((https?://${URL_CHARS})\\)`, "g");
+
+function keepsPreview(url: string): boolean {
+	try {
+		return PREVIEWED_HOSTS.includes(new URL(url).hostname);
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Wraps links in `<…>` so Discord does not unfold a preview card for each cited source.
+ * GIF and video links keep their preview. Trailing sentence punctuation stays outside.
+ */
+export function quietLinks(text: string): string {
+	const bare = text.replace(BARE_URL, (match, before: string, raw: string) => {
+		const url = raw.replace(/[.,;:!?'\]]+$/, "");
+		if (keepsPreview(url)) return match;
+		return `${before}<${url}>${raw.slice(url.length)}`;
+	});
+	return bare.replace(MARKDOWN_URL, (match, url: string) =>
+		keepsPreview(url) ? match : `](<${url}>)`,
+	);
+}

package/src/core/presentation/reply-splitter.ts

@@ -0,0 +1,110 @@
+export const DISCORD_MESSAGE_LIMIT = 2000;
+
+interface Block {
+	text: string;
+	/** The opening fence line when the block is a fenced code block. */
+	fence?: string;
+}
+
+function fenceMarker(openingLine: string): string {
+	return openingLine.trim().slice(0, 3);
+}
+
+/** Paragraphs separated by blank lines; a fenced code block is one block even with blank lines. */
+function parseBlocks(text: string): Block[] {
+	const blocks: Block[] = [];
+	let lines: string[] = [];
+	let fence: string | undefined;
+	const flush = () => {
+		if (lines.some((line) => line.trim())) {
+			blocks.push({ text: lines.join("\n"), fence });
+		}
+		lines = [];
+		fence = undefined;
+	};
+
+	for (const line of text.replace(/\r\n/g, "\n").split("\n")) {
+		if (fence) {
+			lines.push(line);
+			if (line.trim() === fenceMarker(fence)) flush();
+		} else if (/^\s*(```|~~~)/.test(line)) {
+			flush();
+			fence = line;
+			lines.push(line);
+		} else if (!line.trim()) {
+			flush();
+		} else {
+			lines.push(line);
+		}
+	}
+	flush();
+	return blocks;
+}
+
+function hardSplit(text: string, limit: number): string[] {
+	const pieces: string[] = [];
+	let current = "";
+	for (const character of text) {
+		if (current.length + character.length > limit) {
+			pieces.push(current);
+			current = "";
+		}
+		current += character;
+	}
+	if (current) pieces.push(current);
+	return pieces;
+}
+
+/** Packs lines into pieces of at most `limit`, splitting a single overlong line by characters. */
+function packLines(lines: string[], limit: number): string[] {
+	const pieces: string[] = [];
+	let current: string | undefined;
+	for (const line of lines.flatMap((l) =>
+		l.length > limit ? hardSplit(l, limit) : [l],
+	)) {
+		if (current !== undefined && current.length + 1 + line.length <= limit) {
+			current += `\n${line}`;
+		} else {
+			if (current !== undefined) pieces.push(current);
+			current = line;
+		}
+	}
+	if (current !== undefined) pieces.push(current);
+	return pieces;
+}
+
+function splitBlock(block: Block, limit: number): string[] {
+	if (block.text.length <= limit) return [block.text];
+	if (!block.fence) return packLines(block.text.split("\n"), limit);
+
+	// A long code block becomes several complete code blocks, each reopened with the same fence.
+	const marker = fenceMarker(block.fence);
+	const lines = block.text.split("\n");
+	const closed = lines.length > 1 && lines.at(-1)?.trim() === marker;
+	const body = lines.slice(1, closed ? -1 : undefined);
+	const overhead = block.fence.length + 1 + 1 + marker.length;
+	return packLines(body, limit - overhead).map(
+		(piece) => `${block.fence}\n${piece}\n${marker}`,
+	);
+}
+
+/** Splits a reply into Discord messages on paragraph and code-block boundaries. */
+export function splitReply(
+	text: string,
+	limit = DISCORD_MESSAGE_LIMIT,
+): string[] {
+	const chunks: string[] = [];
+	let current: string | undefined;
+	for (const piece of parseBlocks(text).flatMap((block) =>
+		splitBlock(block, limit),
+	)) {
+		if (current !== undefined && current.length + 2 + piece.length <= limit) {
+			current += `\n\n${piece}`;
+		} else {
+			if (current !== undefined) chunks.push(current);
+			current = piece;
+		}
+	}
+	if (current !== undefined) chunks.push(current);
+	return chunks;
+}

package/src/core/presentation/thinking-line.ts

@@ -0,0 +1,24 @@
+import { DISCORD_MESSAGE_LIMIT } from "./reply-splitter.ts";
+
+/** Kept well inside the message limit, since every line also carries the `-#` prefix. */
+export const THINKING_LIMIT = 1_200;
+
+/**
+ * The assistant's thinking as one quiet Discord message: small grey text, blank lines dropped so the
+ * subheading style holds, and cut with an ellipsis when it runs long.
+ */
+export function thinkingLine(thinking: string): string | undefined {
+	const text = thinking.trim();
+	if (!text) return undefined;
+	const cut =
+		text.length > THINKING_LIMIT ? `${text.slice(0, THINKING_LIMIT)}…` : text;
+	const message = cut
+		.split("\n")
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.map((line) => `-# ${line}`)
+		.join("\n");
+	return message.length > DISCORD_MESSAGE_LIMIT
+		? message.slice(0, DISCORD_MESSAGE_LIMIT - 1)
+		: message;
+}

package/src/core/public-entry.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const ROOT = resolve(import.meta.dir, "../..");
+const CORE = join(ROOT, "src/core");
+
+/** The core's modules, tests and test helpers aside. */
+function modules(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory())
+			return entry.name === "testing" ? [] : modules(path);
+		return entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")
+			? [path]
+			: [];
+	});
+}
+
+/** The packages a module imports, by their bare names. */
+function packages(file: string): string[] {
+	const source = readFileSync(file, "utf8");
+	return [
+		...source.matchAll(/(?:from|import)\s*\(?\s*"([^."][^"]*)"/g),
+	].flatMap((match) => (match[1] ? [match[1]] : []));
+}
+
+/** Services only the first consumer's deployment runs; the core must work without them. */
+const PRIVATE = new RegExp(
+	// Spelled in pieces so this test does not itself name the private services.
+	["j" + "ev", "phoe" + "nix", "context" + "forge", "type" + "safe"].join("|"),
+	"i",
+);
+
+describe("the public core", () => {
+	test("imports no package of a private service", () => {
+		const found = modules(CORE).flatMap((file) =>
+			packages(file)
+				.filter((name) => PRIVATE.test(name))
+				.map((name) => `${relative(ROOT, file)} -> ${name}`),
+		);
+		expect(found).toEqual([]);
+	});
+
+	test("every module loads with no consumer configuration", () => {
+		const imports = modules(CORE)
+			.map((file) => `await import(${JSON.stringify(file)});`)
+			.join("\n");
+		const run = Bun.spawnSync({
+			cmd: [process.execPath, "-e", imports],
+			cwd: ROOT,
+			// Only what a process needs to start; none of a consumer's variables.
+			env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "" },
+			stderr: "pipe",
+		});
+		expect(run.stderr.toString()).toBe("");
+		expect(run.exitCode).toBe(0);
+	});
+});