pi-roundtable 0.1.0 → 0.2.1

package/src/core/testing/database.ts

@@ -3,15 +3,9 @@ import type { SQL } from "bun";
 import { type Migration, migrate, openPool } from "../db/migrations.ts";
 
 // PostgreSQL-backed tests run only when ROUNDTABLE_TEST_DATABASE_URL points at a test database.
-// CI sets it; without it `bun test` skips those suites instead of failing to connect.
+// Repository CI requires it in the workflow; consumers without it skip these suites.
 const url = process.env.ROUNDTABLE_TEST_DATABASE_URL;
 
-if (process.env.CI && !url) {
-	throw new Error(
-		"ROUNDTABLE_TEST_DATABASE_URL is not set; CI must run the PostgreSQL-backed tests.",
-	);
-}
-
 /** The guild the stores of the tests serve. */
 export const TEST_GUILD = "900000000000000001";
 

package/src/core/testing/eager-catalog.ts

@@ -0,0 +1,30 @@
+import { messages, setLocale } from "../i18n/index.ts";
+import { setTimeZone } from "../time.ts";
+
+const EAGER = "EAGER:";
+
+/**
+ * Puts the process under a catalog whose every text carries a mark and a foreign time zone, so a
+ * value built before the host applied its environment can be recognised with `eagerText`;
+ * `useTestLocale()` gives the neutral defaults back.
+ */
+export function useEagerCatalog(): void {
+	setTimeZone("America/New_York");
+	setLocale("en", { assistant: "Before", root: "before" });
+	const marked: Record<string, string> = {};
+	for (const [key, value] of Object.entries(messages()))
+		if (typeof value === "string") marked[key] = `${EAGER}${key}`;
+	setLocale("en", {
+		assistant: "Before",
+		root: "before",
+		overrides: marked as Partial<ReturnType<typeof messages>>,
+	});
+}
+
+/** Every marked string under the value; functions are not called, so lazy text stays hidden. */
+export function eagerText(value: unknown, seen = new Set<unknown>()): string[] {
+	if (typeof value === "string") return value.startsWith(EAGER) ? [value] : [];
+	if (typeof value !== "object" || value === null || seen.has(value)) return [];
+	seen.add(value);
+	return Object.values(value).flatMap((child) => eagerText(child, seen));
+}

package/src/core/testing/locale.ts

@@ -1,8 +1,26 @@
-import { setLocale } from "../i18n/index.ts";
+import { type Locale, setLocale } from "../i18n/index.ts";
 import { setTimeZone } from "../time.ts";
 
-/** The neutral defaults the core's suite runs under; a test that changes them puts them back with this. */
-export function useTestLocale(): void {
-	setTimeZone("UTC");
-	setLocale("en", { assistant: "Roundtable", root: "roundtable" });
+/** What a test file runs under; the core's own suite uses the neutral defaults. */
+export interface TestLocale {
+	locale?: Locale;
+	/** An IANA time zone. */
+	timeZone?: string;
+	/** The assistant's display name in catalog text. */
+	assistant?: string;
+	/** The root slash command's name, without the slash. */
+	root?: string;
+}
+
+/**
+ * Puts the process under a locale and time zone, UTC and English with neutral names unless given.
+ * Call it with nothing to hand back the neutral defaults a test that changed them found. It takes
+ * a defaulted object so a hook can receive it without waiting for a callback.
+ */
+export function useTestLocale(options: TestLocale = {}): void {
+	setTimeZone(options.timeZone ?? "UTC");
+	setLocale(options.locale ?? "en", {
+		assistant: options.assistant ?? "Roundtable",
+		root: options.root ?? "roundtable",
+	});
 }

package/src/core/testing/modules.ts

@@ -1,13 +1,24 @@
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { SQL } from "bun";
+import { OWNER_TARGET } from "../agents/agent-claim.ts";
+import { DISCORD, type DiscordServices } from "../builtin/discord.ts";
+import { discordAdminPlugin } from "../builtin/discord-admin.ts";
 import { modulesPlugin } from "../builtin/modules.ts";
+import { skillsPlugin } from "../builtin/skills.ts";
+import { memoryPlugin } from "../builtin/stores.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
 import { silentLogger } from "../log.ts";
-import type { Contribution, PluginContext } from "../plugin.ts";
+import type { SkillStore } from "../modules/skills/skill-store.ts";
 import {
-	type CoreDiscord,
-	CoreRegistry,
-	type CoreStores,
-} from "../services.ts";
+	type Contribution,
+	type PluginContext,
+	pluginContext,
+	type RoundtablePlugin,
+} from "../plugin.ts";
+import { ServiceRegistry } from "../registry/services.ts";
+import { surfacePort } from "../routing/surface-port.ts";
+import type { AgentServer, MemoryStore, ScheduleStore } from "../services.ts";
+import { AGENTS, MEMORY, SCHEDULES } from "../services.ts";
 
 /** What the modules' tools did, for a test to read. */
 export interface ModuleRecord {
@@ -27,41 +38,13 @@ export async function setUpModules(
 ): Promise<{
 	contribution: Contribution;
 	record: ModuleRecord;
-	core: CoreRegistry;
+	services: ServiceRegistry;
 }> {
 	const record: ModuleRecord = {
 		threadOrigins: [],
 		reportChannels: [],
 		ownerChannelAsked: 0,
 	};
-	const core = new CoreRegistry();
-	// SAFETY: the tools under test read no store; each stub is asked for nothing else.
-	core.provide("stores", {
-		memory: {},
-		schedules: {},
-		confirmations: {},
-		agents: {},
-		skills: {},
-	} as unknown as CoreStores);
-	// SAFETY: the tools under test use the surface's owner channel and the threads' open only.
-	core.provide("discord", {
-		surface: {
-			ownerChannel: async () => {
-				record.ownerChannelAsked += 1;
-				return OWNER_CHANNEL;
-			},
-			ownerDiscord: () => ({}),
-		},
-		threads: {
-			open: async (origin: ChannelKey | undefined) => {
-				record.threadOrigins.push(origin);
-				return undefined;
-			},
-		},
-		guard: {},
-		cards: {},
-		studio: {},
-	} as unknown as CoreDiscord);
 	const plugin = modulesPlugin({
 		owner: {
 			id: "1",
@@ -78,20 +61,101 @@ export async function setUpModules(
 			thinking: "low",
 			worker: { run: async () => "found it" },
 		},
-		...(options.agentChannelOf
-			? { agentChannelOf: options.agentChannelOf }
-			: {}),
 	});
-	// SAFETY: setup reads only the logger, the conversations' background, and the core services.
+	const services = new ServiceRegistry([plugin]);
+	// SAFETY: the tools under test read no store; each stub is asked for nothing else.
+	services.preset(MEMORY, {} as MemoryStore);
+	services.preset(SCHEDULES, {} as ScheduleStore);
+	// SAFETY: the schedule tools ask the agent team for a channel and nothing else.
+	if (options.agentChannelOf)
+		services.preset(AGENTS, {
+			team: { channelOf: options.agentChannelOf },
+		} as unknown as AgentServer);
+	// SAFETY: the tools under test use the connection's owner channel and the threads' open only.
+	services.preset(DISCORD, {
+		connection: {
+			ownerChannel: async () => {
+				record.ownerChannelAsked += 1;
+				return OWNER_CHANNEL;
+			},
+			ownerOperations: () => ({}),
+		},
+		threads: {
+			open: async (origin: ChannelKey | undefined) => {
+				record.threadOrigins.push(origin);
+				return undefined;
+			},
+		},
+		guard: {},
+		commands: { add: () => undefined },
+	} as unknown as DiscordServices);
+	// SAFETY: setup reads only the logger, the conversations' background and targets, the surfaces, and the services.
 	const context = {
 		logger: silentLogger(),
 		conversations: {
+			target: (name: string) =>
+				name === OWNER_TARGET.name ? OWNER_TARGET : undefined,
 			background: async (turn: { channel: ChannelKey }) => {
 				record.reportChannels.push(turn.channel);
 				return { status: "ran" };
 			},
 		},
-		core,
-	} as unknown as PluginContext;
-	return { contribution: await plugin.setup(context), record, core };
+		// Only Discord's channels have a surface; any other conversation has none to report in.
+		surfaces: surfacePort(() => [
+			{
+				surface: "discord",
+				start: async () => undefined,
+				sendReply: async () => undefined,
+			},
+		]),
+	} as unknown as Omit<PluginContext, "services">;
+	const contribution = await services.setUp(plugin, () =>
+		plugin.setup(pluginContext(plugin, context, services.forPlugin(plugin))),
+	);
+	return { contribution, record, services };
+}
+
+/** What each addon plugin contributes, set up over stand-ins as far as setup reads them. */
+export async function setUpAddons(): Promise<{
+	memory: Contribution;
+	discordAdmin: Contribution;
+	skills: Contribution;
+}> {
+	const owner = {
+		id: "1",
+		name: "Owner",
+		pronouns: { subject: "they", object: "them", possessive: "their" },
+	} as const;
+	const memory = memoryPlugin({ owner });
+	const admin = discordAdminPlugin({ owner });
+	// SAFETY: the tools under test read the store only when a skill tool runs.
+	const store = { skills: () => [] } as unknown as SkillStore;
+	const skills = skillsPlugin(
+		{
+			guildId: "g1",
+			reposDir: "/tmp/repos",
+			writtenDir: "/tmp/written",
+			builtinDir: "/tmp/builtin",
+		},
+		async () => store,
+	);
+	const services = new ServiceRegistry([memory, admin, skills]);
+	// SAFETY: the admin tools ask the surface for the owner's Discord only when one runs.
+	services.preset(DISCORD, {
+		connection: { ownerOperations: () => ({}) },
+	} as unknown as DiscordServices);
+	// SAFETY: setup reads only the logger, the database handle, and the services.
+	const context = {
+		logger: silentLogger(),
+		database: () => ({}) as SQL,
+	} as unknown as Omit<PluginContext, "services">;
+	const setUp = (plugin: RoundtablePlugin) =>
+		services.setUp(plugin, () =>
+			plugin.setup(pluginContext(plugin, context, services.forPlugin(plugin))),
+		);
+	return {
+		memory: await setUp(memory),
+		discordAdmin: await setUp(admin),
+		skills: await setUp(skills),
+	};
 }

package/src/core/testing/test-host.ts

@@ -0,0 +1,279 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	type ExtensionAPI,
+	type ExtensionFactory,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { DISCORD, type DiscordServices } from "../builtin/discord.ts";
+import { type RoundtableConfig, resolveConfig } from "../config/config.ts";
+import type { ConversationPort } from "../contract/channels.ts";
+import type { AgentRuntime } from "../contract/runtime.ts";
+import type { ChatSurface } from "../contract/surface.ts";
+import { defineRoundtable } from "../define-roundtable.ts";
+import { CommandCollection } from "../discord/command-collection.ts";
+import type { ComposedCommands } from "../discord/compose-commands.ts";
+import type { DiscordConnection } from "../discord/connection.ts";
+import type {
+	CommandGuard,
+	InteractionContribution,
+} from "../discord/interaction-module.ts";
+import { OwnerGuard, ownerRootCommand } from "../discord/owner-command.ts";
+import { Roundtable } from "../host.ts";
+import { silentLogger } from "../log.ts";
+import type { PluginContext, RoundtablePlugin } from "../plugin.ts";
+import { CompactionTiers } from "../runtime/compaction-tiers.ts";
+import { sessionExtensions } from "../runtime/runtime-types.ts";
+import type { AgentTurnScope, SessionContext } from "../sessions.ts";
+import { testDatabaseUrl } from "./database.ts";
+
+export interface TestHostOptions {
+	/**
+	 * Over a test configuration: an owner, a guild, a temporary `dataDir`, and the test database
+	 * (`ROUNDTABLE_TEST_DATABASE_URL`).
+	 */
+	config?: Partial<RoundtableConfig>;
+	/** The app's plugins, after the built-in ones, as `defineRoundtable` places them. */
+	plugins?: readonly RoundtablePlugin[];
+	/** The runtime every turn runs on; by default one that answers "" and builds no Pi session. */
+	runtime?: AgentRuntime;
+	/** What the stand-in Discord hands out. */
+	discord?: Partial<Pick<DiscordConnection, "agentChannels" | "ownerChannel">>;
+}
+
+export interface TestHost {
+	/** A probe plugin's context, set up after every other plugin. */
+	context: PluginContext;
+	/** The host's conversations, as a surface would drive them. */
+	conversations: ConversationPort;
+	commands: {
+		/** Every slash-command contribution the plugins handed Discord, in the order added. */
+		added: readonly InteractionContribution[];
+		/** The tree Discord would register under the root command; closes the collection to later additions. */
+		composed(): ComposedCommands;
+	};
+	/** The tools each extension of a session registers, in plan order; the owner's session unless a scope is given. */
+	sessionTools(
+		scope?: AgentTurnScope,
+	): Promise<{ extension: string; tools: string[] }[]>;
+	/** A session context as the runtime builds it, with the real compaction wrapper. */
+	sessionContext(scope?: AgentTurnScope): SessionContext;
+	/** Stops the host, services first-started last. */
+	stop(): Promise<void>;
+}
+
+function defaultConfig(): RoundtableConfig {
+	const dataDir = mkdtempSync(join(tmpdir(), "roundtable-test-host-"));
+	return {
+		owner: { id: "100000000000000001", name: "Ada" },
+		discord: {
+			token: "token",
+			guild: "900000000000000001",
+			entryChannel: "900000000000000002",
+		},
+		database: { url: testDatabaseUrl },
+		dataDir,
+		model: "anthropic/claude-sonnet-5-5",
+		http: {
+			publicUrl: "https://bot.example.com",
+			socketPath: join(dataDir, "public.sock"),
+		},
+		agents: [
+			{
+				name: "librarian",
+				displayName: "Librarian",
+				prompt: "You keep the reading list.",
+				avatarPrompt: "A calm librarian",
+			},
+		],
+	};
+}
+
+/** A runtime that answers nothing, so the agent server builds no Pi session. */
+function quietRuntime(): AgentRuntime {
+	return {
+		runTurn: async () => ({ ok: true, text: "" }),
+		steer: async () => false,
+		stop: () => false,
+		startFresh: async () => undefined,
+		deleteConversation: async () => undefined,
+		pendingConfirmation: () => undefined,
+		heldActions: async () => undefined,
+		recentTranscript: async () => [],
+	};
+}
+
+/** A Discord that connects to nothing, recording the commands added to it, standing in for the built-in plugin that does. */
+function standInDiscord(
+	commands: CommandCollection,
+	guard: CommandGuard,
+	given: TestHostOptions["discord"],
+): RoundtablePlugin {
+	const surface: ChatSurface = {
+		surface: "discord",
+		start: async () => undefined,
+		sendReply: async () => undefined,
+	};
+	return {
+		name: "test-discord",
+		provides: [DISCORD],
+		replaces: [DISCORD],
+		setup: ({ services }) => {
+			// SAFETY: the plugins after it read only these members while they set up; the rest is read when a tool runs, which a test host does not do.
+			services.provide(DISCORD, {
+				connection: {
+					agentChannels: () => ({}),
+					agentDashboard: () => ({ show: async () => undefined }),
+					onChannelDeleted: () => undefined,
+					ownerChannel: async () => "discord:owner-dm",
+					ownerOperations: () => ({}),
+					...given,
+				},
+				commands: commands.registrar,
+				guard,
+				threads: { open: async () => undefined, sweep: async () => undefined },
+			} as unknown as DiscordServices);
+			return { surfaces: [surface] };
+		},
+	};
+}
+
+/** Anything an extension may call or read on the Pi API besides registering a tool: accepted, does nothing. */
+type Ignored = (...args: readonly never[]) => Ignored;
+
+function ignored(): Ignored {
+	return new Proxy((() => ignored()) as Ignored, {
+		get: (target, key) => (key === "then" ? undefined : target),
+	});
+}
+
+/** The tools a factory registers, by name; every other registration (handlers, commands, events) is accepted and ignored. */
+async function registeredBy(factory: ExtensionFactory): Promise<string[]> {
+	const names: string[] = [];
+	// SAFETY: a session factory only registers tools, handlers and commands; the fake records the tool names and ignores the rest.
+	const registerTool = (tool: { name: string }) => names.push(tool.name);
+	const api = new Proxy(
+		{},
+		{
+			get: (_target, key) =>
+				key === "registerTool" ? registerTool : ignored(),
+		},
+	) as unknown as ExtensionAPI;
+	await factory(api);
+	return names;
+}
+
+const noop: ExtensionFactory = () => undefined;
+/** The core's own extensions, which a session here does not load: only the plugins' registrations are listed. */
+const CORE_EXTENSIONS = {
+	readAttachment: noop,
+	confirmationGate: noop,
+	askUser: noop,
+	selfCompactGuard: noop,
+	activeTools: noop,
+};
+
+/**
+ * Boots `defineRoundtable` over the test database with Discord and the runtime standing in, so
+ * a test sees the built-in plugins and the app's plugins as a host runs them. It needs
+ * PostgreSQL: run it under `describeDb`. Stop it when the test ends.
+ */
+export async function testHost(
+	options: TestHostOptions = {},
+): Promise<TestHost> {
+	const commands = new CommandCollection();
+	const runtime = options.runtime ?? quietRuntime();
+	let captured: PluginContext | undefined;
+	const probe: RoundtablePlugin = {
+		name: "probe",
+		setup: (context) => {
+			captured = context;
+			return { services: [{ name: "probe" }] };
+		},
+	};
+	const base: RoundtableConfig = { ...defaultConfig(), ...options.config };
+	const resolved = resolveConfig(base);
+	const { rootCommand } = resolved.discord;
+	const guard = new OwnerGuard(resolved.owner.id, silentLogger(), rootCommand);
+	const config: RoundtableConfig = {
+		...base,
+		plugins: [
+			standInDiscord(commands, guard, options.discord),
+			{
+				name: "test-runtime",
+				providers: { runtime: () => runtime },
+				setup: () => ({}),
+			},
+			...(options.plugins ?? []),
+			probe,
+		],
+	};
+	const defined = await defineRoundtable(config, { logger: silentLogger() });
+	const roundtable = new Roundtable(defined.options, defined.plugins);
+	await roundtable.run();
+	if (!captured) throw new Error("the probe was not set up");
+	const context = captured;
+	const ownerChannel = await (
+		options.discord?.ownerChannel ?? (async () => "discord:owner-dm" as const)
+	)();
+	/** A group seat's turns run in the group's channel; an agent's in its own. */
+	const turnChannelOf = (scope?: AgentTurnScope) =>
+		scope?.group ? scope.session : scope?.home;
+	const sessionContext = (scope?: AgentTurnScope): SessionContext => {
+		const tiers = new CompactionTiers(
+			SessionManager.inMemory(tmpdir()),
+			() => undefined,
+			context.sessions().plan.compaction?.engine,
+		);
+		const built: SessionContext = {
+			kind: scope ? "agent" : "owner",
+			homeChannel: scope?.home ?? ownerChannel,
+			turnChannel: turnChannelOf(scope) ?? ownerChannel,
+			compaction: {
+				wrap: (compactor) => tiers.wrapCompactor(compactor, () => undefined),
+			},
+			speaker: () => undefined,
+			runTask: async () => {
+				throw new Error("a test host session cannot run tasks");
+			},
+		};
+		if (scope) built.agent = scope;
+		return built;
+	};
+	return {
+		context,
+		conversations: context.conversations,
+		commands: {
+			added: commands.added(),
+			composed: () => commands.compose(ownerRootCommand(rootCommand)),
+		},
+		sessionTools: async (scope) => {
+			const tools: { extension: string; tools: string[] }[] = [];
+			for (const extension of sessionExtensions(
+				context.sessions().plan,
+				sessionContext(scope),
+				CORE_EXTENSIONS,
+			))
+				tools.push({
+					extension: extension.name,
+					tools: await registeredBy(extension.factory),
+				});
+			return tools;
+		},
+		sessionContext,
+		stop: async () => {
+			await roundtable.shutdown("test");
+		},
+	};
+}
+
+/** The default delegation worker reads pi-web-access, which a checkout has and the exported package does not list. */
+export function hasWebAccess(): boolean {
+	try {
+		import.meta.resolve("pi-web-access/package.json");
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/core/testing/tool-set.ts

@@ -0,0 +1,64 @@
+import { ASK_USER_TOOL } from "../runtime/extensions/ask-user.ts";
+import { COMPACT_TOOL } from "../runtime/extensions/self-compact-guard.ts";
+import { AGENTS } from "../services.ts";
+import type { AgentTurnScope } from "../sessions.ts";
+import type { TestHost } from "./test-host.ts";
+
+export const scout: AgentTurnScope = {
+	name: "scout",
+	session: "discord:scout",
+	home: "discord:scout",
+};
+export const seat: AgentTurnScope = {
+	name: "scout",
+	session: "discord:war-room",
+	home: "discord:scout",
+	group: "war-room",
+};
+
+/** Tools the core's own extensions and pi-web-access register, which no fake session here loads. */
+const NAMED_ELSEWHERE = [
+	ASK_USER_TOOL,
+	COMPACT_TOOL,
+	"read_attachment",
+	"web_search",
+	"fetch_content",
+	"get_search_content",
+];
+
+export interface ToolSet {
+	sessions: Record<string, { tools: string[]; selection?: string[] }>;
+	tiers: Record<string, string>;
+}
+
+/** The tools each kind of session registers or selects under the host's plugins, and the tier each needs. */
+export async function captureToolSet(host: TestHost): Promise<ToolSet> {
+	const out: ToolSet = { sessions: {}, tiers: {} };
+	const names = new Set<string>(NAMED_ELSEWHERE);
+	const seatSelection = (scope: AgentTurnScope | undefined) => {
+		if (!scope) return undefined;
+		// SAFETY: the concrete team reads its selection, which no port publishes.
+		const team = host.context.services.get(AGENTS).team as unknown as {
+			selection(scope: AgentTurnScope): { tools: string[] };
+		};
+		return [...team.selection(scope).tools].sort();
+	};
+	for (const [label, scope] of [
+		["owner", undefined],
+		["agent", scout],
+		["group seat", seat],
+	] as const) {
+		const tools = (await host.sessionTools(scope)).flatMap(
+			(extension) => extension.tools,
+		);
+		const selection = seatSelection(scope);
+		out.sessions[label] = {
+			tools: [...tools].sort(),
+			...(selection ? { selection } : {}),
+		};
+		for (const name of [...tools, ...(selection ?? [])]) names.add(name);
+	}
+	for (const name of [...names].sort())
+		out.tiers[name] = host.context.toolTiers.minTier(name);
+	return out;
+}

package/src/core/time.ts

@@ -16,8 +16,13 @@ export function timeZone(): string {
 
 /** The formatter is constructed when used, not at import time, so configuration is observed. */
 function stamp(at: Date): string {
+	return zonedStampIn(at, zone);
+}
+
+/** `at` as "YYYY-MM-DD HH:MM" in the named IANA time zone, whatever the host chose. */
+export function zonedStampIn(at: Date, timeZone: string): string {
 	return new Intl.DateTimeFormat("sv-SE", {
-		timeZone: zone,
+		timeZone,
 		year: "numeric",
 		month: "2-digit",
 		day: "2-digit",