pi-roundtable 0.1.0 → 0.2.1

package/src/testing.ts

@@ -1,12 +1,41 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SQL } from "bun";
-import type { ConversationPort } from "./core/contract/channels.ts";
+import { agentClaim, OWNER_TARGET } from "./core/agents/agent-claim.ts";
+import { DISCORD } from "./core/builtin/discord.ts";
+import type {
+	ConversationPort,
+	InboundMessage,
+} from "./core/contract/channels.ts";
 import type { Providers } from "./core/contract/providers.ts";
+import type {
+	AgentRuntime,
+	HeldActionStore,
+	RuntimeDeps,
+} from "./core/contract/runtime.ts";
+import type { ServiceKey } from "./core/contract/services.ts";
+import type { ChatSurface, SurfacePort } from "./core/contract/surface.ts";
+import { CommandCollection } from "./core/discord/command-collection.ts";
+import type { ComposedCommands } from "./core/discord/compose-commands.ts";
+import type {
+	CommandGuard,
+	CommandRegistrar,
+	InteractionContribution,
+} from "./core/discord/interaction-module.ts";
+import { OwnerGuard, ownerRootCommand } from "./core/discord/owner-command.ts";
+import type { PendingConfirmation } from "./core/domain/conversation.ts";
 import { NotLinkedError, PluginError } from "./core/errors.ts";
 import { EventBus } from "./core/events.ts";
+import type { HoldCheck } from "./core/holds.ts";
+import type { OwnerIdentity } from "./core/identity.ts";
+import { ConfirmationJudge } from "./core/judging/confirmation-judge.ts";
 import { silentLogger } from "./core/log.ts";
+import { ConversationBackgroundTurns } from "./core/modules/background/background-turns.ts";
 import type {
 	Contribution,
+	HostEnv,
 	LinkedSessions,
 	PluginContext,
 	RoundtablePlugin,
@@ -18,15 +47,131 @@ import {
 	linkSessions,
 } from "./core/registry/contributions.ts";
 import { resolveProviders } from "./core/registry/providers.ts";
+import { ServiceRegistry } from "./core/registry/services.ts";
 import { ChannelQueue } from "./core/routing/channel-queue.ts";
-import { CoreRegistry } from "./core/services.ts";
-import type { SessionContext } from "./core/sessions.ts";
-import type { Speaker } from "./core/speakers.ts";
+import { ChannelRouter } from "./core/routing/channel-router.ts";
+import {
+	type ConversationTurns,
+	conversationTurns,
+} from "./core/routing/conversation-turns.ts";
+import { surfacePort } from "./core/routing/surface-port.ts";
+import { AGENTS, type AgentServer, BACKGROUND_TURNS } from "./core/services.ts";
+import type { ChannelKey, SessionContext } from "./core/sessions.ts";
+import { type Speaker, speakerPolicy } from "./core/speakers.ts";
 import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
 
+// Fixtures for plugin tests.
+
+export { silentLogger } from "./core/log.ts";
+
+export type { TestStore } from "./core/testing/database.ts";
+export {
+	describeDb,
+	openTestStore,
+	TEST_GUILD,
+	testDatabaseUrl,
+} from "./core/testing/database.ts";
+export { eagerText, useEagerCatalog } from "./core/testing/eager-catalog.ts";
+export type { TestLocale } from "./core/testing/locale.ts";
+export { useTestLocale } from "./core/testing/locale.ts";
+
+export { OWNER_SPEAKER } from "./core/testing/owner.ts";
+export type { TestHost, TestHostOptions } from "./core/testing/test-host.ts";
+export { testHost } from "./core/testing/test-host.ts";
+export type { FakeThreadHost } from "./core/testing/thread-host.ts";
+export { fakeThreads } from "./core/testing/thread-host.ts";
+
+/**
+ * A service the plugin under test reads, with the members the test gives it, made by
+ * `servicePair(KEY, { ... })`. Reading a member the test did not give throws a PluginError that
+ * names it.
+ */
+export interface ServicePair {
+	readonly key: ServiceKey<unknown>;
+	readonly given: object;
+}
+
+/** Pairs a service key with the members the test gives it, for the `services` option of `testPlugin`. */
+export function servicePair<T extends object>(
+	key: ServiceKey<T>,
+	given: Partial<T>,
+): ServicePair {
+	return { key, given };
+}
+
+/** A stand-in for the Discord plugin's `DISCORD` service, made by `fakeDiscord()`. */
+export interface FakeDiscord {
+	/** Give this to `testPlugin`'s `services` option: `{ services: [discord.service] }`. */
+	readonly service: ServicePair;
+	/** What `DISCORD.commands` is to the plugin: the real registrar, which refuses what the Discord plugin refuses. */
+	readonly commands: CommandRegistrar;
+	/** What `DISCORD.guard` is: the owner, `owner` unless the test gave another id, serving the root command. */
+	readonly guard: CommandGuard;
+	/** Every contribution the plugin added, in the order it added them. */
+	added(): readonly InteractionContribution[];
+	/** The tree the Discord plugin would register, composed under the root command the fake was made with. */
+	compose(): ComposedCommands;
+}
+
+/**
+ * A `DISCORD` service for a plugin that adds slash commands, without a Discord connection: the
+ * plugin's `commands.add` calls are recorded, and `compose()` shows the tree Discord would get.
+ * `rootCommand` is the root command's name, `roundtable` by default. Only `commands` and `guard` are given; reading another member throws.
+ */
+export function fakeDiscord(
+	options: { ownerId?: string; rootCommand?: string } = {},
+): FakeDiscord {
+	const collection = new CommandCollection();
+	const { rootCommand = "roundtable" } = options;
+	const guard = new OwnerGuard(
+		options.ownerId ?? "owner",
+		silentLogger(),
+		rootCommand,
+	);
+	return {
+		service: servicePair(DISCORD, { commands: collection.registrar, guard }),
+		commands: collection.registrar,
+		guard,
+		added: () => collection.added(),
+		compose: () => collection.compose(ownerRootCommand(rootCommand)),
+	};
+}
+
 export interface TestPluginOptions {
+	/** The host environment the plugin sees; default en and UTC. */
+	env?: Partial<HostEnv>;
+	/**
+	 * The owner the runtime's dependencies and the agent server's claim know; default `owner`,
+	 * named Owner, who is addressed as they.
+	 */
+	owner?: { id: string; name: string; pronouns?: OwnerIdentity["pronouns"] };
 	database?: SQL;
 	providers?: Partial<Providers>;
+	/**
+	 * Chat surfaces besides the plugin's own, such as a fake one: they are in `context.surfaces`,
+	 * started with the plugin's services (their messages reach `conversations`), and stopped last.
+	 */
+	surfaces?: readonly ChatSurface[];
+	/**
+	 * What the plugin reads from `context.services`, one `servicePair(KEY, { ... })` per service.
+	 * `servicePair(AGENTS, { runtime })` is the runtime that `context.turns` runs turns on; without
+	 * it, a plugin that fills the `runtime` slot gets the runtime its provider builds. A service
+	 * not given here reads as absent to `find`, and `get` names this option, except for what the
+	 * host supplies anyway: `BACKGROUND_TURNS`, the real background turns over the test's router,
+	 * and, once `AGENTS` is given, its `approvals` (the real confirmation judge over
+	 * `providers.judge`, when the test gives a judge). Giving `AGENTS` a `team` adds the agent
+	 * server's own claim to the router, answering as the host's would for the `owner`.
+	 */
+	services?: readonly ServicePair[];
+	/**
+	 * The plugin's conversations: by default a router over the plugin's own `channels` claims, so a
+	 * message a surface delivers reaches them. Methods given here replace the router's.
+	 */
+	conversations?: Partial<ConversationPort>;
+	/** Replaces `context.turns`, which by default runs turns over the runtime and the surfaces. */
+	turns?: ConversationTurns;
+	/** How long the router holds a bare forward for the message that follows it; the host option `conversations.forwardJoinMs`. */
+	forwardJoinMs?: number;
 }
 
 export interface RecordedEvent {
@@ -36,13 +181,23 @@ export interface RecordedEvent {
 
 export interface TestPluginResult {
 	contribution: Contribution;
+	/** The hold rules the plugin contributed, chained as the host links them: the description of a call that must be approved first, or undefined. */
+	holds: HoldCheck;
+	/** What the plugin sees as `context.conversations`, for a test to drive its claims. */
+	conversations: ConversationPort;
+	/** What the plugin sees as `context.turns`. */
+	turns: ConversationTurns;
+	/** What the plugin sees as `context.surfaces`: its own surfaces and the injected ones. */
+	surfaces: SurfacePort;
+	/** The runtime the plugin's `runtime` provider built, given stand-in dependencies; undefined when it fills no such slot. */
+	runtime: AgentRuntime | undefined;
 	tools: readonly string[];
 	tiers: ToolTierTable;
 	events: RecordedEvent[];
 	runTool(
 		name: string,
 		args: Record<string, unknown>,
-		options?: { speaker?: Speaker },
+		options?: { speaker?: Speaker; channel?: ChannelKey },
 	): Promise<string>;
 	stop(): Promise<void>;
 }
@@ -53,6 +208,10 @@ const NOT_LINKED = {
 		"conversations are linked once every plugin is set up. Use them from a service's start or from a handler, not during setup.",
 	sessions:
 		"session parts are linked once every plugin is set up. Call sessions() from a service's start or from a handler, not during setup.",
+	surfaces:
+		"chat surfaces are linked once every plugin is set up. Use surfaces from a service's start or from a handler, not during setup.",
+	turns:
+		"conversation turns are linked once every plugin is set up. Use turns from a service's start or from a handler, not during setup.",
 	dashboard:
 		"dashboard lines are linked once every plugin is set up. Call dashboard() from a service's start or from a handler, not during setup.",
 };
@@ -61,77 +220,274 @@ function unlinked(part: keyof typeof NOT_LINKED): never {
 	throw new NotLinkedError(NOT_LINKED[part]);
 }
 
+/** Members a probe may ask of any object: a test's partial service is not refused for them. */
+const PROBED = new Set(["then", "toJSON", "asymmetricMatch"]);
+
+/** A service the test gave only some members of: reading another names the option that adds it. */
+function partialService(key: ServiceKey<unknown>, given: object): object {
+	return new Proxy(given, {
+		get(target, member, receiver) {
+			if (member in target || typeof member === "symbol" || PROBED.has(member))
+				return Reflect.get(target, member, receiver);
+			throw new PluginError(
+				`testPlugin gave service ${key.id} no "${member}". Give it in the services option: testPlugin(plugin, { services: [servicePair(KEY, { ${member}: ... })] }).`,
+			);
+		},
+	});
+}
+
+/** Held actions kept in memory, for the runtime a plugin's provider builds under test. */
+function memoryHeldActions(): HeldActionStore {
+	const held = new Map<ChannelKey, PendingConfirmation>();
+	return {
+		load: async (conversation) => held.get(conversation),
+		save: async (conversation, actions) => {
+			if (actions) held.set(conversation, actions);
+			else held.delete(conversation);
+		},
+	};
+}
+
 /** Build one plugin without Discord or PostgreSQL, retaining the host's validation and tier logic. */
+// pi-lens-ignore: high-complexity, large-function — one host's context and lifecycle, mirrored end to end
 export async function testPlugin(
 	plugin: RoundtablePlugin,
 	options: TestPluginOptions = {},
 ): Promise<TestPluginResult> {
 	const logger = silentLogger();
+	const owner = {
+		id: "owner",
+		name: "Owner",
+		pronouns: { subject: "they", object: "them", possessive: "their" },
+		...options.owner,
+	};
 	const tiers = toolTiers();
 	const bus = new EventBus(logger);
 	const events: RecordedEvent[] = [];
-	const core = new CoreRegistry();
+	// The plugin under test is the only one registered, so a service it reads comes from the test.
+	const services = new ServiceRegistry(
+		[plugin],
+		"testPlugin has no built-in plugins: give it in the services option, testPlugin(plugin, { services: [servicePair(KEY, { ... })] }).",
+	);
+	const given = new Map(
+		(options.services ?? []).map((pair) => [pair.key.id, pair] as const),
+	);
+	const agents = given.get(AGENTS.id);
+	const resolved = resolveProviders([plugin]);
 	let linked: LinkedSessions | undefined;
+	let router: ChannelRouter | undefined;
+	const queue = new ChannelQueue();
 	const conversations: ConversationPort = {
-		handle: async () => unlinked("conversations"),
-		background: async () => unlinked("conversations"),
-		startFresh: async () => unlinked("conversations"),
-		deleteConversation: async () => unlinked("conversations"),
-		stop: () => unlinked("conversations"),
-		postsInPlace: () => unlinked("conversations"),
+		handle: async (message) =>
+			(router ?? unlinked("conversations")).handle(message),
+		background: async (turn) =>
+			(router ?? unlinked("conversations")).background(turn),
+		target: (name) => (router ?? unlinked("conversations")).target(name),
+		startFresh: async (channel) =>
+			(router ?? unlinked("conversations")).startFresh(channel),
+		deleteConversation: async (channel) =>
+			(router ?? unlinked("conversations")).deleteConversation(channel),
+		stop: (channel) => (router ?? unlinked("conversations")).stop(channel),
+		postsInPlace: (channel) =>
+			(router ?? unlinked("conversations")).postsInPlace(channel),
+		...options.conversations,
 	};
-	const context: PluginContext = {
+	const surfaces = surfacePort(() =>
+		linked
+			? [...registry.surfaces, ...(options.surfaces ?? [])]
+			: unlinked("surfaces"),
+	);
+	const sink = {
+		turnStarted: (turn: TurnEvent) => {
+			events.push({ name: "turnStarted", turn });
+			bus.sink.turnStarted(turn);
+		},
+		turnEnded: (turn: TurnEndEvent) => {
+			events.push({ name: "turnEnded", turn });
+			bus.sink.turnEnded(turn);
+		},
+		changed: () => {
+			events.push({ name: "changed" });
+			bus.sink.changed();
+		},
+	};
+	const turns: ConversationTurns =
+		options.turns ??
+		conversationTurns({
+			linked: () => {
+				if (!linked) unlinked("turns");
+			},
+			runtime: () => services.get(AGENTS).runtime,
+			surfaces,
+			events: sink,
+			selection: () => (linked ?? unlinked("sessions")).agentSelection(),
+			logger,
+		});
+	const providers = {
+		...resolved,
+		...options.providers,
+		filled: new Set([
+			...resolved.filled,
+			...(Object.keys(options.providers ?? {}) as (keyof Providers)[]),
+		]),
+	};
+	const env: HostEnv = {
+		locale: "en",
+		timeZone: "UTC",
+		now: () => new Date(),
+		...options.env,
+	};
+	// What the agent server does with the slot: the provider's runtime serves `context.turns`.
+	let runtime: AgentRuntime | undefined;
+	if (providers.filled.has("runtime")) {
+		const deps: RuntimeDeps = {
+			logger,
+			env,
+			owner: { id: owner.id, name: owner.name },
+			sessions: () => linked ?? unlinked("sessions"),
+			toolTiers: tiers,
+			prompts: (channel, speaker) => surfaces.prompts(channel, speaker),
+			agents: {
+				workDir: tmpdir(),
+				skills: () => [],
+				modelOf: () => ({ model: "test/model", thinking: "off" }),
+				turnChannel: (scope) => scope.home,
+			},
+			confirmations: memoryHeldActions(),
+			judge: providers.judge,
+		};
+		runtime = providers.runtime(deps);
+		// The provider's runtime serves `context.turns` unless the test gave another.
+		if (!agents || !("runtime" in agents.given))
+			given.set(AGENTS.id, {
+				key: AGENTS,
+				given: { ...agents?.given, runtime } satisfies Partial<AgentServer>,
+			});
+	}
+	// Once the agent server is there, it judges the owner's replies to held actions as the host's does.
+	const server = given.get(AGENTS.id);
+	if (server && providers.filled.has("judge") && !("approvals" in server.given))
+		given.set(AGENTS.id, {
+			key: AGENTS,
+			given: {
+				...server.given,
+				approvals: new ConfirmationJudge({
+					judge: providers.judge,
+					threshold: 0.6,
+					logger,
+				}),
+			} satisfies Partial<AgentServer>,
+		});
+	for (const { key, given: members } of given.values())
+		services.preset(key, partialService(key, members));
+	// The turns nobody wrote run through the same router, unless the test gave others or the plugin provides them.
+	if (
+		!given.has(BACKGROUND_TURNS.id) &&
+		!plugin.provides?.some((key) => key.id === BACKGROUND_TURNS.id)
+	)
+		services.preset(
+			BACKGROUND_TURNS,
+			new ConversationBackgroundTurns({
+				conversations,
+				system: { id: "assistant", name: "Assistant" },
+				logger,
+			}),
+		);
+	const context: Omit<PluginContext, "services"> = {
 		logger,
+		env,
 		sessions: () => linked ?? unlinked("sessions"),
-		queue: new ChannelQueue(),
+		queue,
 		toolTiers: tiers,
-		events: {
-			turnStarted: (turn) => {
-				events.push({ name: "turnStarted", turn });
-				bus.sink.turnStarted(turn);
-			},
-			turnEnded: (turn) => {
-				events.push({ name: "turnEnded", turn });
-				bus.sink.turnEnded(turn);
-			},
-			changed: () => {
-				events.push({ name: "changed" });
-				bus.sink.changed();
-			},
-		},
+		events: sink,
 		conversations,
+		surfaces,
+		turns,
 		database: () => {
 			if (!options.database) throw new PluginError("no database is configured");
 			return options.database;
 		},
-		core,
-		providers: { ...resolveProviders([plugin]), ...options.providers },
+		providers,
 		dashboard: () => (linked ? registry.dashboard : unlinked("dashboard")),
 	};
-	const registry = await collectContributions([plugin], context, tiers);
+	const registry = await collectContributions(
+		[plugin],
+		context,
+		tiers,
+		services,
+	);
 	linked = linkSessions(registry);
 	bus.link(registry.handlers);
+	// With a team given, the agent server's claim and its target are in the router, as on a host.
+	const team = given.get(AGENTS.id)?.given;
+	const agentServer = team && "team" in team ? services.get(AGENTS) : undefined;
+	const attachmentDir = mkdtempSync(join(tmpdir(), "roundtable-test-plugin-"));
+	router = new ChannelRouter({
+		claims: [
+			...(agentServer
+				? [
+						agentClaim({
+							owner,
+							speakers: speakerPolicy({ owners: [owner.id] }),
+							// SAFETY: the claim reads the concrete team's members (guildId, owns, answerOwner, answerGroup, answerBackground, startFresh), which a test that gives a team for it supplies.
+							team: agentServer.team as unknown as Parameters<
+								typeof agentClaim
+							>[0]["team"],
+							runtime: {
+								steer: (...args) => services.get(AGENTS).runtime.steer(...args),
+								stop: (channel) => services.get(AGENTS).runtime.stop(channel),
+							},
+							surface: surfaces,
+							attachmentDir: () => attachmentDir,
+							logger,
+						}),
+					]
+				: []),
+			...registry.channels,
+		],
+		targets: (name) =>
+			registry.backgroundTargets.find((t) => t.name === name) ??
+			(agentServer && name === OWNER_TARGET.name ? OWNER_TARGET : undefined),
+		queue,
+		logger,
+		...(options.forwardJoinMs === undefined
+			? {}
+			: { forwardJoinMs: options.forwardJoinMs }),
+	});
 	const contribution: Contribution = {
 		services: registry.services,
 		events: registry.handlers[0]?.events,
-		interactions: registry.interactions,
 		http: registry.routes,
 		holdRules: registry.holdRules,
 		piPackages: registry.piPackages,
 		sessionTools: registry.sessionTools,
 		channels: registry.channels,
+		surfaces: registry.surfaces,
+		personas: registry.personas,
+		backgroundTargets: registry.backgroundTargets,
 		dashboard: registry.dashboard,
 		tools: registry.tools,
 		seeds: registry.seeds,
 		prompt: registry.prompt,
+		requiredTools: registry.requiredTools,
 		...(registry.agentSelections.length > 0
 			? { agentSelection: linked.agentSelection }
 			: {}),
 	};
+	// The plugin's own surfaces start as services; the injected ones start beside them, after.
+	const deliver = (message: InboundMessage) =>
+		void conversations.handle(message);
 	for (const service of registry.services) await service.start?.();
+	for (const surface of options.surfaces ?? []) await surface.start(deliver);
+	await runtime?.preflight?.();
 	let stopped = false;
 	return {
 		contribution,
+		holds: linked.holds,
+		conversations,
+		turns,
+		surfaces,
+		runtime,
 		tools: registry.tools.map((tool) => tool.name),
 		tiers,
 		events,
@@ -148,10 +504,11 @@ export async function testPlugin(
 					isError?: boolean;
 				}>;
 			}[] = [];
+			const channel = runOptions?.channel ?? "test:1";
 			const session = {
 				kind: "agent",
-				homeChannel: "test:1",
-				turnChannel: "test:1",
+				homeChannel: channel,
+				turnChannel: channel,
 				compaction: { wrap: (factory) => factory },
 				speaker: () => runOptions?.speaker,
 				runTask: async () => {
@@ -175,8 +532,11 @@ export async function testPlugin(
 			if (stopped) return;
 			stopped = true;
 			await bus.deliver("shutdown", []);
+			for (const surface of (options.surfaces ?? []).toReversed())
+				await surface.stop?.();
 			for (const service of registry.services.toReversed())
 				await service.stop?.();
+			await runtime?.dispose?.();
 		},
 	};
 }

package/examples/guide.test.ts

@@ -1,52 +0,0 @@
-import { expect, test } from "bun:test";
-import { readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const root = join(import.meta.dir, "..");
-const guide = readFileSync(join(root, "docs/plugins.md"), "utf8");
-const files = readdirSync(import.meta.dir).filter((name) =>
-	name.endsWith(".ts"),
-);
-const examples = files.filter(
-	(name) => !name.endsWith(".test.ts") && name !== "guide.test.ts",
-);
-
-/** The guide embeds a file as a `ts` block between these two markers. */
-const MARKER = /<!-- example: (\S+) -->/g;
-const BLOCK =
-	/<!-- example: (\S+) -->\n```ts\n([\s\S]*?)\n```\n<!-- \/example -->/g;
-
-test("every marker in the guide wraps one ts block", () => {
-	expect([...guide.matchAll(BLOCK)].length).toBe(
-		[...guide.matchAll(MARKER)].length,
-	);
-	expect([...guide.matchAll(MARKER)].length).toBeGreaterThan(0);
-});
-
-test("every block in the guide is exactly the file it names", () => {
-	for (const [, path, embedded] of guide.matchAll(BLOCK)) {
-		const file = readFileSync(join(root, path as string), "utf8");
-		expect({ path, code: embedded }).toEqual({ path, code: file.trimEnd() });
-	}
-});
-
-test("every example is embedded in the guide and has a test beside it", () => {
-	const embedded = [...guide.matchAll(MARKER)].map((match) => match[1]);
-	for (const name of examples) {
-		expect(embedded).toContain(`examples/${name}`);
-		expect(files).toContain(name.replace(/\.ts$/, ".test.ts"));
-	}
-});
-
-test("examples import only the public entries, typebox, bun, and their neighbors", () => {
-	for (const name of files.filter((file) => file !== "guide.test.ts")) {
-		const source = readFileSync(join(import.meta.dir, name), "utf8");
-		for (const [, specifier] of source.matchAll(/from "([^"]+)"/g))
-			expect({ name, specifier }).toEqual({
-				name,
-				specifier: expect.stringMatching(
-					/^(pi-roundtable|pi-roundtable\/testing|typebox|bun|bun:test|\.\/[a-z-]+\.ts)$/,
-				),
-			});
-	}
-});