pi-roundtable 0.1.0 → 0.2.1

package/examples/echo-runtime.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+	definePlugin,
+	PluginError,
+	Roundtable,
+	type RoundtablePlugin,
+} from "pi-roundtable";
+import { OWNER_SPEAKER, silentLogger, testPlugin } from "pi-roundtable/testing";
+import { createEchoRuntime, EchoRuntime, echoRuntime } from "./echo-runtime.ts";
+import { FakeSurface } from "./fake-surface.ts";
+
+/** One host runs per process, so each test stops its own. */
+const hosts: Roundtable[] = [];
+afterEach(async () => {
+	for (const host of hosts.splice(0)) await host.shutdown("test");
+});
+
+function host(plugins: RoundtablePlugin[]): Roundtable {
+	const roundtable = new Roundtable({ logger: silentLogger() }, plugins);
+	hosts.push(roundtable);
+	return roundtable;
+}
+
+test("the harness builds the runtime from the slot, the way the agent server does", async () => {
+	const harness = await testPlugin(echoRuntime);
+	expect(harness.runtime).toBeInstanceOf(EchoRuntime);
+	await harness.stop();
+});
+
+test("a turn run through context.turns goes through the plugin's runtime, and the answer goes out through the surface", async () => {
+	const surface = new FakeSurface();
+	const harness = await testPlugin(echoRuntime, { surfaces: [surface] });
+	const result = await harness.turns.run({
+		channel: "fake:room",
+		kind: "owner",
+		text: "hello",
+		speaker: OWNER_SPEAKER,
+	});
+	expect(result).toEqual({ ok: true, text: "[owner] hello" });
+	expect(surface.replies).toEqual([
+		{ channel: "fake:room", reply: { chunks: ["[owner] hello"] } },
+	]);
+	// The surface showed typing and the stop control while the turn ran.
+	expect(surface.typing).toEqual(["start fake:room", "stop fake:room"]);
+	expect(surface.stops).toEqual(["show fake:room", "hide fake:room"]);
+	expect(harness.events.map(({ name }) => name)).toEqual([
+		"turnStarted",
+		"turnEnded",
+	]);
+	await harness.stop();
+});
+
+test("an agent's turn carries its scope, and its conversation is the scope's session", async () => {
+	const harness = await testPlugin(echoRuntime);
+	const { runtime } = harness;
+	if (!runtime) throw new Error("the plugin fills the runtime slot");
+	const result = await runtime.runTurn({
+		channel: "fake:agent-room",
+		selection: { id: "agent", tools: [], groups: [] },
+		text: "status?",
+		agent: {
+			name: "infra",
+			session: "fake:agent-room",
+			home: "fake:agent-room",
+		},
+	});
+	expect(result).toEqual({ ok: true, text: "[agent infra] status?" });
+	expect(await runtime.recentTranscript("fake:agent-room", 10)).toEqual([
+		{ role: "user", text: "status?" },
+		{ role: "assistant", text: "[agent infra] status?" },
+	]);
+	await runtime.startFresh("fake:agent-room");
+	expect(await runtime.recentTranscript("fake:agent-room", 10)).toEqual([]);
+	await harness.stop();
+});
+
+test("a turn of a kind nobody wrote a persona for fails with the fix, and the surface says so", async () => {
+	const surface = new FakeSurface();
+	const harness = await testPlugin(echoRuntime, { surfaces: [surface] });
+	const result = await harness.turns.run({
+		channel: "fake:room",
+		kind: "quiz",
+		text: "hello",
+		speaker: OWNER_SPEAKER,
+	});
+	expect(result.ok).toBe(false);
+	expect(!result.ok && result.error.message).toContain("`personas`");
+	expect(surface.replies).toHaveLength(1);
+	await harness.stop();
+});
+
+test("the host resolves the slot to the plugin's factory", async () => {
+	let filled = false;
+	const probe = definePlugin({
+		name: "probe",
+		setup: ({ providers }) => {
+			filled = providers.filled.has("runtime");
+			expect(providers.runtime).toBe(createEchoRuntime);
+			return { services: [{ name: "probe" }] };
+		},
+	});
+	await host([echoRuntime, probe]).run();
+	expect(filled).toBe(true);
+});
+
+test("only one plugin may fill the runtime slot", async () => {
+	const another = definePlugin({
+		name: "another-runtime",
+		providers: { runtime: createEchoRuntime },
+		setup: () => ({}),
+	});
+	const error = await host([echoRuntime, another])
+		.run()
+		.then(
+			() => undefined,
+			(failure: unknown) => failure,
+		);
+	expect(error).toBeInstanceOf(PluginError);
+	expect(String(error)).toContain(
+		"provider slot runtime is already filled by plugin echo-runtime",
+	);
+});

package/examples/echo-runtime.ts

@@ -0,0 +1,107 @@
+import {
+	AgentRunError,
+	type AgentRuntime,
+	type ChannelKey,
+	definePlugin,
+	type PendingConfirmation,
+	type RuntimeDeps,
+	type RuntimeFactory,
+	type TranscriptEntry,
+	type TurnRequest,
+	type TurnResult,
+} from "pi-roundtable";
+
+/**
+ * A runtime runs the conversations of the agent server and of every claim that calls
+ * `context.turns.run`: one conversation per channel key, its history, and its held actions.
+ * This one answers with the text it was given, and keeps each conversation's transcript in memory.
+ */
+export class EchoRuntime implements AgentRuntime {
+	readonly #deps: RuntimeDeps;
+	readonly #transcripts = new Map<ChannelKey, TranscriptEntry[]>();
+
+	constructor(deps: RuntimeDeps) {
+		this.#deps = deps;
+	}
+
+	async runTurn(request: TurnRequest): Promise<TurnResult> {
+		// An agent's turn carries the agent's scope, and its conversation is the scope's session.
+		const conversation = request.agent?.session ?? request.channel;
+		const prompt = this.#promptOf(request);
+		if (prompt === undefined)
+			return {
+				ok: false,
+				error: new AgentRunError(
+					`no persona for the conversation kind "${request.kind}": a plugin adds one with \`personas\``,
+				),
+			};
+		const text = `[${prompt}] ${request.text}`;
+		const transcript = this.#transcripts.get(conversation) ?? [];
+		transcript.push(
+			{ role: "user", text: request.text },
+			{ role: "assistant", text },
+		);
+		this.#transcripts.set(conversation, transcript);
+		return { ok: true, text };
+	}
+
+	/** What a model would get as its system prompt: the agent's name, or the persona of the kind. */
+	#promptOf(request: TurnRequest): string | undefined {
+		if (request.agent) return `agent ${request.agent.name}`;
+		// Only the turn's kind picks the persona; "owner" is the kind of a turn that names none.
+		const kind = request.kind ?? "owner";
+		return kind === "owner"
+			? (this.#deps.sessions().persona("owner") ?? "owner")
+			: this.#deps.sessions().persona(kind);
+	}
+
+	/** Nothing runs long enough to take a steering message, so each waits for its own turn. */
+	async steer(): Promise<boolean> {
+		return false;
+	}
+
+	/** No turn outlives its `runTurn`, so there is never one to stop. */
+	stop(): boolean {
+		return false;
+	}
+
+	async startFresh(conversation: ChannelKey): Promise<void> {
+		this.#transcripts.delete(conversation);
+	}
+
+	async deleteConversation(conversation: ChannelKey): Promise<void> {
+		this.#transcripts.delete(conversation);
+	}
+
+	/** This runtime holds no actions for approval; a real one keeps them in `deps.confirmations`. */
+	pendingConfirmation(): PendingConfirmation | undefined {
+		return undefined;
+	}
+
+	async heldActions(): Promise<PendingConfirmation | undefined> {
+		return undefined;
+	}
+
+	async recentTranscript(
+		conversation: ChannelKey,
+		limit: number,
+	): Promise<TranscriptEntry[]> {
+		return (this.#transcripts.get(conversation) ?? []).slice(-limit);
+	}
+}
+
+/** The factory the agent server calls once, with what a runtime needs from the host. */
+export const createEchoRuntime: RuntimeFactory = (deps) => {
+	deps.logger.info("the echo runtime replaces Pi");
+	return new EchoRuntime(deps);
+};
+
+/**
+ * A plugin fills the `runtime` slot to replace the whole conversation runtime; without one the
+ * agent server builds the Pi runtime. One plugin may fill it.
+ */
+export const echoRuntime = definePlugin({
+	name: "echo-runtime",
+	providers: { runtime: createEchoRuntime },
+	setup: () => ({}),
+});

package/examples/events.test.ts

@@ -9,6 +9,7 @@ test("the handlers record a turn, a team change, and the shutdown", async () =>
 	// The harness does not deliver the core's events: call the handlers with the payload the core sends.
 	const turn = {
 		agent: "guide",
+		kind: "agent",
 		channel: "discord:1",
 		speaker: undefined,
 	} as const;

package/examples/events.ts

@@ -7,10 +7,10 @@ export function turnLog(lines: string[]) {
 		setup: () => ({
 			events: {
 				turnStarted: (turn) => {
-					lines.push(`${turn.agent} started`);
+					lines.push(`${turn.agent ?? turn.kind} started`);
 				},
 				turnEnded: (turn) => {
-					lines.push(`${turn.agent} ${turn.result}`);
+					lines.push(`${turn.agent ?? turn.kind} ${turn.result}`);
 				},
 				changed: () => {
 					lines.push("team changed");

package/examples/fake-surface.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+	type ChatSurface,
+	definePlugin,
+	NotLinkedError,
+	PluginError,
+	Roundtable,
+	type RoundtablePlugin,
+	type SurfacePort,
+} from "pi-roundtable";
+import { silentLogger } from "pi-roundtable/testing";
+import { FakeSurface, fakeChat } from "./fake-surface.ts";
+
+/** One host runs per process, so each test stops its own. */
+const hosts: Roundtable[] = [];
+afterEach(async () => {
+	for (const host of hosts.splice(0)) await host.shutdown("test");
+});
+
+function host(
+	plugins: RoundtablePlugin[],
+	options: Partial<ConstructorParameters<typeof Roundtable>[0]> = {},
+): Roundtable {
+	const roundtable = new Roundtable(
+		{ logger: silentLogger(), ...options },
+		plugins,
+	);
+	hosts.push(roundtable);
+	return roundtable;
+}
+
+async function until(done: () => boolean): Promise<void> {
+	for (let waited = 0; !done() && waited < 1000; waited += 5)
+		await Bun.sleep(5);
+	expect(done()).toBe(true);
+}
+
+/** The surface port the host gave a plugin, for a test to call once the host is running. */
+function portOf(): { plugin: RoundtablePlugin; port: () => SurfacePort } {
+	let port: SurfacePort | undefined;
+	return {
+		plugin: definePlugin({
+			name: "port-probe",
+			setup: ({ surfaces }) => {
+				port = surfaces;
+				return { services: [{ name: "probe" }] };
+			},
+		}),
+		port: () => {
+			if (!port) throw new Error("the plugin was not set up");
+			return port;
+		},
+	};
+}
+
+test("a message of the surface reaches the claim on its keys, and the reply goes out through the surface", async () => {
+	const surface = new FakeSurface();
+	await host([fakeChat(surface)]).run();
+	surface.say("fake:room", "hello");
+	await until(() => surface.replies.length > 0);
+	expect(surface.replies).toEqual([
+		{ channel: "fake:room", reply: { chunks: ["echo: hello"] } },
+	]);
+	expect(surface.typing).toEqual(["start fake:room", "stop fake:room"]);
+});
+
+test("a message whose channel belongs to another surface is dropped, not handed to the claim", async () => {
+	const surface = new FakeSurface();
+	await host([fakeChat(surface)]).run();
+	surface.say("discord:room", "hello");
+	await Bun.sleep(30);
+	expect(surface.replies).toEqual([]);
+	surface.say("fake:room", "again");
+	await until(() => surface.replies.length > 0);
+	expect(surface.replies.map(({ channel }) => channel)).toEqual(["fake:room"]);
+});
+
+test("the port picks the surface by the key's prefix and refuses a prefix nobody serves", async () => {
+	const surface = new FakeSurface();
+	const probe = portOf();
+	await host([fakeChat(surface), probe.plugin]).run();
+	const surfaces = probe.port();
+	expect(surfaces.of("fake:1")).toBe(surface);
+	expect(surfaces.of("mcp:1")).toBeUndefined();
+	await surfaces.sendReply("fake:1", { chunks: ["hi"] });
+	expect(surface.replies).toHaveLength(1);
+	const refused = await surfaces.sendReply("mcp:1", { chunks: ["hi"] }).then(
+		() => undefined,
+		(error: unknown) => error,
+	);
+	expect(refused).toBeInstanceOf(PluginError);
+	expect(String(refused)).toContain("mcp");
+	// What a surface does not show is a no-op, and a prefix nobody serves has nothing to show.
+	surfaces.showStop("fake:1")();
+	surfaces.showStop("mcp:1")();
+	surfaces.startTyping("mcp:1")();
+	expect(surface.stops).toEqual(["show fake:1", "hide fake:1"]);
+});
+
+test("the owner's approvals in a channel of the surface use the surface's prompts, and other channels have none", async () => {
+	const surface = new FakeSurface();
+	const probe = portOf();
+	await host([fakeChat(surface), probe.plugin]).run();
+	const prompts = probe.port().prompts("fake:1");
+	expect(await prompts?.confirm("Run rm?", "deletes the notes")).toBe(
+		"approved",
+	);
+	expect(surface.asked).toEqual(["fake:1: Run rm?"]);
+	expect(probe.port().prompts("mcp:1")).toBeUndefined();
+});
+
+test("two surfaces with one prefix are refused, naming both plugins", async () => {
+	const second = definePlugin({
+		name: "second-chat",
+		setup: () => ({ surfaces: [new FakeSurface()] }),
+	});
+	const error = await host([fakeChat(new FakeSurface()), second])
+		.run()
+		.then(
+			() => undefined,
+			(failure: unknown) => failure,
+		);
+	expect(error).toBeInstanceOf(PluginError);
+	expect(String(error)).toContain(
+		"surface fake is already registered by plugin fake-chat",
+	);
+});
+
+test("a surface is started before the plugin's own services and stopped after them", async () => {
+	const log: string[] = [];
+	const surface: ChatSurface = {
+		surface: "log",
+		start: async () => void log.push("start surface"),
+		stop: async () => void log.push("stop surface"),
+		sendReply: async () => undefined,
+	};
+	const plugin = definePlugin({
+		name: "log-chat",
+		setup: () => ({
+			services: [
+				{
+					name: "after",
+					start: () => void log.push("start service"),
+					stop: () => void log.push("stop service"),
+				},
+			],
+			surfaces: [surface],
+		}),
+	});
+	const roundtable = host([plugin]);
+	await roundtable.run();
+	await roundtable.shutdown("test");
+	expect(log).toEqual([
+		"start surface",
+		"start service",
+		"stop service",
+		"stop surface",
+	]);
+});
+
+test("surfaces are not available during setup", async () => {
+	const early = definePlugin({
+		name: "early",
+		setup: ({ surfaces }) => {
+			surfaces.of("fake:1");
+			return {};
+		},
+	});
+	const error = await host([early])
+		.run()
+		.then(
+			() => undefined,
+			(failure: unknown) => failure,
+		);
+	expect(error).toBeInstanceOf(PluginError);
+	expect(String(error)).toContain(
+		"chat surfaces are linked once every plugin is set up",
+	);
+	expect((error as PluginError).cause).toBeInstanceOf(NotLinkedError);
+});

package/examples/fake-surface.ts

@@ -0,0 +1,109 @@
+import {
+	type ChannelKey,
+	type ChatSurface,
+	definePlugin,
+	type InboundMessage,
+	type OutboundReply,
+	type OwnerPrompts,
+	parseChannelKey,
+} from "pi-roundtable";
+
+/**
+ * A chat surface connects the host to one chat network. This one is an in-memory chat: its
+ * channels are the keys that start with `fake:`, and it records what the host asks of it. A real
+ * surface talks to its network in `start` and `sendReply`, and skips the optional methods it
+ * cannot do.
+ */
+export class FakeSurface implements ChatSurface {
+	readonly surface = "fake";
+	readonly replies: { channel: ChannelKey; reply: OutboundReply }[] = [];
+	readonly typing: string[] = [];
+	readonly stops: string[] = [];
+	readonly asked: string[] = [];
+	#deliver: ((message: InboundMessage) => void) | undefined;
+
+	/** The host hands over its router; every message the network reports goes to it. */
+	async start(deliver: (message: InboundMessage) => void): Promise<void> {
+		this.#deliver = deliver;
+	}
+
+	async stop(): Promise<void> {
+		this.#deliver = undefined;
+	}
+
+	/** Someone writes in a channel. */
+	say(channel: ChannelKey, text: string): void {
+		this.#deliver?.({
+			channel,
+			messageId: `m${this.replies.length}`,
+			authorId: "1",
+			authorName: "Ada",
+			authorIsBot: false,
+			isDirect: true,
+			mentionsBot: false,
+			repliesToBot: false,
+			text,
+			attachments: [],
+		});
+	}
+
+	async sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void> {
+		this.replies.push({ channel, reply });
+	}
+
+	startTyping(channel: ChannelKey): () => void {
+		this.typing.push(`start ${channel}`);
+		return () => void this.typing.push(`stop ${channel}`);
+	}
+
+	showStop(channel: ChannelKey): () => void {
+		this.stops.push(`show ${channel}`);
+		return () => void this.stops.push(`hide ${channel}`);
+	}
+
+	/** How the owner would approve a held action or answer a question in a turn. */
+	prompts(channel: ChannelKey): OwnerPrompts {
+		return {
+			confirm: async (title) => {
+				this.asked.push(`${channel}: ${title}`);
+				return "approved";
+			},
+			ask: async () => undefined,
+		};
+	}
+}
+
+/**
+ * The plugin contributes the surface, and a claim that owns the channels of its prefix and
+ * answers through `context.surfaces`, which picks the surface by the prefix of the channel's key.
+ */
+export function fakeChat(surface: FakeSurface) {
+	return definePlugin({
+		name: "fake-chat",
+		setup: ({ surfaces }) => ({
+			surfaces: [surface],
+			channels: [
+				{
+					name: "fake-channels",
+					priority: 10,
+					owns: (channel) => parseChannelKey(channel).surface === "fake",
+					admit: (message) => ({
+						kind: "turn",
+						run: async () => {
+							const stopTyping = surfaces.startTyping(message.channel);
+							try {
+								await surfaces.sendReply(message.channel, {
+									chunks: [`echo: ${message.text}`],
+								});
+							} finally {
+								stopTyping();
+							}
+						},
+						failure: "a fake chat turn failed",
+					}),
+					startFresh: async () => "The fake chat has nothing to start over.",
+				},
+			],
+		}),
+	});
+}

package/examples/interactions.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "bun:test";
-import { testPlugin } from "pi-roundtable/testing";
+import { fakeDiscord, testPlugin } from "pi-roundtable/testing";
 import { ping } from "./interactions.ts";
 
 /** The parts of a Discord interaction the module reads. */
@@ -14,8 +14,9 @@ function fake(subcommand: string, replies: string[]) {
 }
 
 test("the module answers /roundtable ping and ignores other subcommands", async () => {
-	const harness = await testPlugin(ping);
-	const [added] = harness.contribution.interactions ?? [];
+	const discord = fakeDiscord();
+	const harness = await testPlugin(ping, { services: [discord.service] });
+	const [added] = discord.added();
 	expect(added?.rootOptions?.map((option) => option.name)).toEqual(["ping"]);
 	const replies: string[] = [];
 	expect(await added?.module.handle(fake("ping", replies))).toBe(true);
@@ -23,3 +24,11 @@ test("the module answers /roundtable ping and ignores other subcommands", async
 	expect(replies).toEqual(["pong"]);
 	await harness.stop();
 });
+
+test("the tree Discord would register has the subcommand under the root", async () => {
+	const discord = fakeDiscord();
+	await (await testPlugin(ping, { services: [discord.service] })).stop();
+	const { commands } = discord.compose();
+	expect(commands.map((command) => command.name)).toEqual(["roundtable"]);
+	expect(commands[0]?.options?.map((option) => option.name)).toEqual(["ping"]);
+});

package/examples/interactions.ts

@@ -1,28 +1,28 @@
 import { definePlugin } from "pi-roundtable";
+import { DISCORD } from "pi-roundtable/discord";
 
 /**
- * Interactions add slash commands. A subcommand goes under the one root command (`/roundtable`
- * by default); the module answers the interactions Discord sends and returns true for the ones it handled.
+ * Slash commands belong to the Discord plugin: a plugin adds its own from setup with
+ * `commands.add`. A subcommand goes under the one root command (`/roundtable` by default); the
+ * module answers the interactions Discord sends and returns true for the ones it handled.
  */
 export const ping = definePlugin({
 	name: "ping",
-	setup: () => ({
-		interactions: [
-			{
-				rootOptions: [
-					{ type: 1, name: "ping", description: "Check that the bot answers" },
-				],
-				module: {
-					commands: () => [],
-					handle: async (interaction) => {
-						if (!interaction.isChatInputCommand()) return false;
-						if (interaction.options.getSubcommand(false) !== "ping")
-							return false;
-						await interaction.reply("pong");
-						return true;
-					},
+	setup: ({ services }) => {
+		services.get(DISCORD).commands.add({
+			rootOptions: [
+				{ type: 1, name: "ping", description: "Check that the bot answers" },
+			],
+			module: {
+				commands: () => [],
+				handle: async (interaction) => {
+					if (!interaction.isChatInputCommand()) return false;
+					if (interaction.options.getSubcommand(false) !== "ping") return false;
+					await interaction.reply("pong");
+					return true;
 				},
 			},
-		],
-	}),
+		});
+		return {};
+	},
 });

package/examples/shared-services.test.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "bun:test";
+import { definePlugin, PluginError, Roundtable } from "pi-roundtable";
+import { servicePair, silentLogger, testPlugin } from "pi-roundtable/testing";
+import {
+	NOTE_INDEX,
+	type NoteIndex,
+	noteReader,
+	notes,
+	shoutingNotes,
+} from "./shared-services.ts";
+
+/** Runs a host over the plugins, and stops it again. */
+async function withHost(
+	plugins: ConstructorParameters<typeof Roundtable>[1],
+	inside: () => void,
+) {
+	const roundtable = new Roundtable({ logger: silentLogger() }, plugins);
+	await roundtable.run();
+	try {
+		inside();
+	} finally {
+		await roundtable.shutdown("test");
+	}
+}
+
+/** A plugin that writes a note, as any plugin after the notes may. */
+const writer = definePlugin({
+	name: "writer",
+	setup: ({ services }) => {
+		services.get(NOTE_INDEX).add("hi");
+		return { services: [{ name: "writer" }] };
+	},
+});
+
+test("a plugin reads what the plugin before it provided", async () => {
+	const seen: (readonly string[] | undefined)[] = [];
+	await withHost(
+		[notes(), writer, noteReader((list) => seen.push(list))],
+		() => {
+			expect(seen).toEqual([["hi"]]);
+		},
+	);
+});
+
+test("a plugin under test gets the service it reads from the harness, and find is undefined without it", async () => {
+	const seen: (readonly string[] | undefined)[] = [];
+	const given: NoteIndex = { add: () => undefined, all: () => ["a", "b"] };
+	const harness = await testPlugin(
+		noteReader((list) => seen.push(list)),
+		{ services: [servicePair(NOTE_INDEX, given)] },
+	);
+	const bare = await testPlugin(noteReader((list) => seen.push(list)));
+	await harness.stop();
+	await bare.stop();
+	expect(seen).toEqual([["a", "b"], undefined]);
+});
+
+test("a replacement takes the place of the plugin that provided the key, and everyone after it reads the replacement", async () => {
+	const seen: (readonly string[] | undefined)[] = [];
+	await withHost(
+		[notes(), shoutingNotes(), writer, noteReader((list) => seen.push(list))],
+		() => expect(seen).toEqual([["HI"]]),
+	);
+});
+
+test("a provider that does not provide what it lists is refused after setup", async () => {
+	await expect(
+		testPlugin({
+			name: "forgetful",
+			provides: [NOTE_INDEX],
+			setup: () => ({ services: [{ name: "idle" }] }),
+		}),
+	).rejects.toBeInstanceOf(PluginError);
+});