pi-roundtable 0.7.19 → 0.9.0

package/examples/channel-context.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "bun:test";
+import type { ChatSurface, InboundMessage } from "pi-roundtable";
+import type { ChannelContext } from "pi-roundtable/discord";
+import { fakeDiscord, testPlugin } from "pi-roundtable/testing";
+import { tavern } from "./channel-context.ts";
+import { createEchoRuntime } from "./echo-runtime.ts";
+
+const AROUND: ChannelContext = {
+	messages: [
+		{
+			id: "40",
+			authorId: "7",
+			authorName: "Kai",
+			bot: false,
+			owner: false,
+			text: "I open the cellar door",
+			at: new Date(0),
+		},
+	],
+	text: '## Channel messages since your last answer\n<channel-context>\n<message from="Kai" id="7" role="member">I open the cellar door</message>\n</channel-context>',
+};
+
+/** A server message from the owner in the tavern's channel. */
+function addressed(extra: Partial<InboundMessage> = {}): InboundMessage {
+	return {
+		channel: "discord:500",
+		messageId: "50",
+		authorId: "owner",
+		authorName: "Ada",
+		authorIsBot: false,
+		isDirect: false,
+		space: "9",
+		mentionsBot: true,
+		repliesToBot: false,
+		text: "What do we find?",
+		attachments: [],
+		...extra,
+	};
+}
+
+async function serving() {
+	const asked: { message: InboundMessage; keep?: number }[] = [];
+	const replies: string[] = [];
+	// The Discord surface as far as the turn's reply goes: `context.turns` posts through it.
+	const surface: ChatSurface = {
+		surface: "discord",
+		start: async () => undefined,
+		sendReply: async (_channel, reply) => {
+			replies.push(reply.chunks.join(""));
+		},
+	};
+	const harness = await testPlugin(tavern(["500"]), {
+		surfaces: [surface],
+		providers: { runtime: createEchoRuntime },
+		services: [
+			fakeDiscord({
+				channelContext: async (message, options) => {
+					asked.push({
+						message,
+						...(options?.keep ? { keep: options.keep } : {}),
+					});
+					return AROUND;
+				},
+			}).service,
+		],
+	});
+	return { asked, replies, harness };
+}
+
+test("an addressed message's turn carries the channel context after its text", async () => {
+	const { asked, replies, harness } = await serving();
+	await harness.conversations.handle(addressed());
+	expect(asked).toEqual([
+		{ message: expect.objectContaining({ messageId: "50" }), keep: 20 },
+	]);
+	expect(replies).toEqual([
+		`[You keep the tavern's table. Answer the person who addressed you.] What do we find?\n\n${AROUND.text}`,
+	]);
+	await harness.stop();
+});
+
+test("a message that does not address the assistant gets no turn and reads nothing", async () => {
+	const { asked, replies, harness } = await serving();
+	await harness.conversations.handle(addressed({ mentionsBot: false }));
+	expect(asked).toEqual([]);
+	expect(replies).toEqual([]);
+	await harness.stop();
+});

package/examples/channel-context.ts

@@ -0,0 +1,62 @@
+import { definePlugin, parseChannelKey } from "pi-roundtable";
+import { DISCORD, withChannelContext } from "pi-roundtable/discord";
+
+/** The kind of the tavern's conversations. */
+const TAVERN = "tavern";
+
+/**
+ * A claim that opts in to channel context: in the Discord channels it owns it answers only the
+ * messages that mention the assistant or reply to it, and each turn also reads what the others
+ * said there since the assistant last posted. The context is public channel text appended to the
+ * turn's text; the people who wrote it do not become speakers.
+ */
+export function tavern(channelIds: readonly string[]) {
+	return definePlugin({
+		name: "tavern",
+		setup: ({ turns, services }) => {
+			const discord = services.get(DISCORD);
+			return {
+				personas: [
+					{
+						kind: TAVERN,
+						prompt: () =>
+							"You keep the tavern's table. Answer the person who addressed you.",
+					},
+				],
+				channels: [
+					{
+						name: "tavern",
+						priority: 10,
+						owns: (channel) => {
+							const { surface, id } = parseChannelKey(channel);
+							return surface === "discord" && channelIds.includes(id);
+						},
+						admit: (message) => {
+							const { speaker } = message;
+							if (message.authorIsBot || !speaker) return undefined;
+							if (!message.mentionsBot && !message.repliesToBot)
+								return undefined;
+							return {
+								kind: "turn",
+								run: async () => {
+									// Once per answered message, inside `run`: what it returns is not returned again.
+									const around = await discord.channelContext(message, {
+										keep: 20,
+									});
+									await turns.run({
+										channel: message.channel,
+										kind: TAVERN,
+										text: withChannelContext(message.text, around),
+										speaker,
+									});
+								},
+								failure: "a tavern turn failed",
+							};
+						},
+						startFresh: async () => TAVERN,
+					},
+				],
+			};
+		},
+	});
+}

package/examples/discord-adapter.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { $ } from "bun";
+import { defineRoundtable, type RoundtableConfig } from "pi-roundtable";
+import { silentLogger } from "pi-roundtable/testing";
+import { withDiscordAdapter } from "./discord-adapter.ts";
+
+const ENV: Record<string, string> = {
+	OWNER_ID: "100000000000000001",
+	OWNER_NAME: "Ada",
+	DISCORD_TOKEN: "token",
+	DISCORD_GUILD_ID: "900000000000000001",
+	DISCORD_ENTRY_CHANNEL_ID: "900000000000000002",
+	DATABASE_URL: "postgres://localhost/roundtable",
+	MODEL: "anthropic/claude-sonnet-5-5",
+	PUBLIC_URL: "https://bot.example.com",
+};
+
+test("a Discord adapter assembles the plugins the top-level discord does, in the same order", async () => {
+	const dataDir = `${Bun.env.TMPDIR ?? "/tmp"}/discord-adapter-${crypto.randomUUID()}`;
+	const adapted = withDiscordAdapter((name) => ENV[name] ?? "", dataDir);
+	const { adapters: _adapters, ...rest } = adapted;
+	const topLevel: RoundtableConfig = {
+		...rest,
+		discord: {
+			token: "token",
+			guild: "900000000000000001",
+			entryChannel: "900000000000000002",
+		},
+	};
+	const names = async (config: RoundtableConfig) =>
+		(await defineRoundtable(config, { logger: silentLogger() })).plugins.map(
+			(plugin) => plugin.name,
+		);
+	try {
+		const plugins = await names(adapted);
+		expect(plugins).toContain("discord");
+		expect(plugins).toContain("agent-server");
+		expect(plugins).toEqual(await names(topLevel));
+	} finally {
+		await $`rm -rf ${dataDir}`;
+	}
+});

package/examples/discord-adapter.ts

@@ -0,0 +1,26 @@
+import type { RoundtableConfig } from "pi-roundtable";
+import { discord } from "pi-roundtable/discord";
+
+/**
+ * Discord as an adapter: `discord()` takes the same settings as the top-level `discord`, and the
+ * host assembles the same plugins in the same order. Configure Discord in one place, not both.
+ */
+export function withDiscordAdapter(
+	env: (name: string) => string,
+	dataDir: string,
+): RoundtableConfig {
+	return {
+		owner: { id: env("OWNER_ID"), name: env("OWNER_NAME") },
+		adapters: [
+			discord({
+				token: env("DISCORD_TOKEN"),
+				guild: env("DISCORD_GUILD_ID"),
+				entryChannel: env("DISCORD_ENTRY_CHANNEL_ID"),
+			}),
+		],
+		database: { url: env("DATABASE_URL") },
+		dataDir,
+		model: env("MODEL"),
+		http: { publicUrl: env("PUBLIC_URL") },
+	};
+}

package/examples/echo-runtime.test.ts

@@ -58,6 +58,7 @@ test("an agent's turn carries its scope, and its conversation is the scope's ses
 		channel: "fake:agent-room",
 		selection: { id: "agent", tools: [], groups: [] },
 		text: "status?",
+		speaker: OWNER_SPEAKER,
 		agent: {
 			name: "infra",
 			session: "fake:agent-room",

package/examples/echo-runtime.ts

@@ -98,7 +98,7 @@ export const createEchoRuntime: RuntimeFactory = (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.
+ * runtime plugin builds the Pi runtime. One plugin may fill it.
  */
 export const echoRuntime = definePlugin({
 	name: "echo-runtime",

package/examples/fake-surface.test.ts

@@ -4,11 +4,16 @@ import {
 	definePlugin,
 	NotLinkedError,
 	PluginError,
+	promptScope,
 	Roundtable,
 	type RoundtablePlugin,
 	type SurfacePort,
 } from "pi-roundtable";
-import { silentLogger } from "pi-roundtable/testing";
+import {
+	describeSurfaceContract,
+	type SurfaceObservation,
+	silentLogger,
+} from "pi-roundtable/testing";
 import { FakeSurface, fakeChat } from "./fake-surface.ts";
 
 /** One host runs per process, so each test stops its own. */
@@ -97,18 +102,76 @@ test("the port picks the surface by the key's prefix and refuses a prefix nobody
 	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 () => {
+test("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",
+	const speaker = {
+		id: "1",
+		name: "Ada",
+		tier: "member",
+		principalId: "p1",
+	} as const;
+	const prompts = probe.port().prompts("fake:1", promptScope(speaker));
+	const answer = prompts?.confirm(
+		"Search?",
+		"searches the web",
+		undefined,
+		"member",
 	);
-	expect(surface.asked).toEqual(["fake:1: Run rm?"]);
+	expect(surface.asked).toEqual([
+		{ id: "q1", channel: "fake:1", title: "Search?", open: true },
+	]);
+	surface.answer("q1", { principalId: "p1" }, true);
+	expect(await answer).toBe("approved");
 	expect(probe.port().prompts("mcp:1")).toBeUndefined();
 });
 
+/** The fake chat as the contract sees it: what its person, author "1", has seen. */
+function contractSubject(tier: "owner" | "member") {
+	const surface = new FakeSurface();
+	return {
+		surface,
+		channel: "fake:room" as const,
+		speaker: { id: "1", name: "Ada", tier, principalId: "p1" },
+		write: async (text: string) => surface.say("fake:room", text),
+		observations: (): SurfaceObservation[] => [
+			...surface.replies.map(({ reply }) => ({
+				kind: "reply" as const,
+				text: reply.chunks.join("\n"),
+				files: [],
+			})),
+			...surface.typing.map((entry) => ({
+				kind: "typing" as const,
+				on: entry.startsWith("start"),
+			})),
+			...surface.stops.map((entry) => ({
+				kind: "stop" as const,
+				on: entry.startsWith("show"),
+			})),
+			...surface.asked.flatMap(({ id, title, open }) => [
+				{ kind: "prompt" as const, id, title },
+				...(open ? [] : [{ kind: "prompt_closed" as const, id }]),
+			]),
+		],
+		answer: async (id: string, approved: boolean) =>
+			surface.answer(id, { principalId: "p1" }, approved),
+		stranger: {
+			answer: async (id: string, approved: boolean) =>
+				surface.answer(id, { principalId: "p2" }, approved),
+		},
+		owner: {
+			answer: async (id: string, approved: boolean) =>
+				surface.answer(id, { principalId: "p0", owner: true }, approved),
+		},
+	};
+}
+
+describeSurfaceContract("the fake chat", async () => contractSubject("owner"));
+describeSurfaceContract("the fake chat for a member", async () =>
+	contractSubject("member"),
+);
+
 test("two surfaces with one prefix are refused, naming both plugins", async () => {
 	const second = definePlugin({
 		name: "second-chat",

package/examples/fake-surface.ts

@@ -1,13 +1,24 @@
 import {
+	type Approval,
 	type ChannelKey,
 	type ChatSurface,
 	definePlugin,
 	type InboundMessage,
 	type OutboundReply,
-	type OwnerPrompts,
+	type PromptScope,
+	type Prompts,
 	parseChannelKey,
+	TIERS,
 } from "pi-roundtable";
 
+/** A prompt the surface showed, open until someone it is for answers it. */
+interface Asked {
+	id: string;
+	channel: ChannelKey;
+	title: string;
+	open: boolean;
+}
+
 /**
  * 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
@@ -19,7 +30,12 @@ export class FakeSurface implements ChatSurface {
 	readonly replies: { channel: ChannelKey; reply: OutboundReply }[] = [];
 	readonly typing: string[] = [];
 	readonly stops: string[] = [];
-	readonly asked: string[] = [];
+	readonly asked: Asked[] = [];
+	/** Who may answer each open prompt, and how it settles. */
+	readonly #answering = new Map<
+		string,
+		{ principalId?: string; owners: boolean; settle(answer: Approval): void }
+	>();
 	#deliver: ((message: InboundMessage) => void) | undefined;
 
 	/** The host hands over its router; every message the network reports goes to it. */
@@ -61,16 +77,66 @@ export class FakeSurface implements ChatSurface {
 		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 {
+	/**
+	 * How a turn asks to approve a held action or answers a question. The scope names who may
+	 * answer: its speaker when their tier holds the call, and the owners unless the conversation
+	 * is private, where a call above the speaker's tier goes to no one and expires at once.
+	 */
+	prompts(channel: ChannelKey, scope?: PromptScope): Prompts {
 		return {
-			confirm: async (title) => {
-				this.asked.push(`${channel}: ${title}`);
-				return "approved";
+			confirm: async (title, _message, signal, minTier = "owner") => {
+				const theirs =
+					scope !== undefined &&
+					TIERS.indexOf(scope.tier) >= TIERS.indexOf(minTier);
+				const owners = scope?.escalate !== "none";
+				if (!theirs && !owners) return "expired";
+				return this.#ask(channel, title, signal, {
+					...(theirs ? { principalId: scope.principalId } : {}),
+					owners,
+				});
 			},
 			ask: async () => undefined,
 		};
 	}
+
+	/** Someone answers an open prompt; it settles only when it is theirs to answer. */
+	answer(
+		id: string,
+		who: { principalId: string; owner?: boolean },
+		approved: boolean,
+	): void {
+		const open = this.#answering.get(id);
+		if (!open) return;
+		const theirs = open.principalId === who.principalId;
+		if (theirs || (who.owner && open.owners))
+			open.settle(approved ? "approved" : "declined");
+	}
+
+	#ask(
+		channel: ChannelKey,
+		title: string,
+		signal: AbortSignal | undefined,
+		audience: { principalId?: string; owners: boolean },
+	): Promise<Approval> {
+		const asked = {
+			id: `q${this.asked.length + 1}`,
+			channel,
+			title,
+			open: true,
+		};
+		this.asked.push(asked);
+		return new Promise((resolve) => {
+			const settle = (answer: Approval) => {
+				this.#answering.delete(asked.id);
+				asked.open = false;
+				resolve(answer);
+			};
+			this.#answering.set(asked.id, { ...audience, settle });
+			signal?.addEventListener("abort", () => settle("cancelled"), {
+				once: true,
+			});
+		});
+	}
 }
 
 /**

package/examples/headless.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+	AGENTS,
+	defineRoundtable,
+	type PluginContext,
+	Roundtable,
+	RUNTIME,
+} from "pi-roundtable";
+import { DISCORD } from "pi-roundtable/discord";
+import {
+	describeDb,
+	silentLogger,
+	testDatabaseUrl,
+} from "pi-roundtable/testing";
+import { echoRuntime } from "./echo-runtime.ts";
+import { FakeSurface } from "./fake-surface.ts";
+import { studyHall } from "./headless.ts";
+
+let roundtable: Roundtable | undefined;
+afterEach(async () => {
+	await roundtable?.shutdown("test");
+	roundtable = undefined;
+});
+
+async function until(done: () => boolean): Promise<void> {
+	for (let waited = 0; !done() && waited < 2000; waited += 5)
+		await Bun.sleep(5);
+	expect(done()).toBe(true);
+}
+
+describeDb("a host without Discord", () => {
+	test("boots without Discord or the agent server and answers a study room through its runtime", async () => {
+		const surface = new FakeSurface();
+		const config = studyHall(surface, {
+			databaseUrl: testDatabaseUrl,
+			dataDir: `${Bun.env.TMPDIR ?? "/tmp"}/study-hall-${crypto.randomUUID()}`,
+		});
+		let context: PluginContext | undefined;
+		const { options, plugins } = await defineRoundtable(
+			{
+				...config,
+				plugins: [
+					...(config.plugins ?? []),
+					// The echo runtime stands in for Pi, so the test calls no model.
+					echoRuntime,
+					{
+						name: "probe",
+						setup: (given) => {
+							context = given;
+							return { services: [{ name: "probe" }] };
+						},
+					},
+				],
+			},
+			{ logger: silentLogger() },
+		);
+		const names = plugins.map((plugin) => plugin.name);
+		expect(names).not.toContain("discord");
+		expect(names).not.toContain("agent-server");
+		expect(options.listeners).toEqual([]);
+		roundtable = new Roundtable(options, plugins);
+		await roundtable.run();
+		expect(context?.services.find(DISCORD)).toBeUndefined();
+		expect(context?.services.find(AGENTS)).toBeUndefined();
+		expect(context?.services.get(RUNTIME)).toBeDefined();
+		surface.say("fake:study-algebra", "What is a group?");
+		await until(() => surface.replies.length > 0);
+		expect(surface.replies[0]?.reply.chunks.join()).toContain(
+			"What is a group?",
+		);
+	});
+});

package/examples/headless.ts

@@ -0,0 +1,35 @@
+import { definePlugin, type RoundtableConfig } from "pi-roundtable";
+import type { FakeSurface } from "./fake-surface.ts";
+import { studyRoom } from "./study-room.ts";
+
+/** A plugin that brings a chat network and nothing else; the study room's claim answers its rooms. */
+export function chatNetwork(surface: FakeSurface) {
+	return definePlugin({
+		name: "chat-network",
+		setup: () => ({ surfaces: [surface] }),
+	});
+}
+
+/**
+ * A host without Discord: no `discord` key, so no Discord plugin, no agent server, no agents and
+ * no skills; and no `http`, so no listener opens until a plugin needs one. Conversations come
+ * through the plugins' own chat surfaces, and `context.turns` runs them on the host's runtime,
+ * Pi's unless a plugin fills the `runtime` slot.
+ */
+export function studyHall(
+	surface: FakeSurface,
+	where: { databaseUrl: string; dataDir: string },
+): RoundtableConfig {
+	return {
+		name: "Study Hall",
+		access: {
+			owners: [{ principal: "owner", name: "Ada" }],
+			// Admit the fake surface's authors explicitly, not in the claim.
+			members: { everyone: ["fake"] },
+		},
+		database: { url: where.databaseUrl },
+		dataDir: where.dataDir,
+		model: "anthropic/claude-sonnet-5-5",
+		plugins: [chatNetwork(surface), studyRoom],
+	};
+}

package/examples/http.test.ts

@@ -1,6 +1,7 @@
 import { expect, test } from "bun:test";
+import type { RouteSocket } from "pi-roundtable";
 import { testPlugin } from "pi-roundtable/testing";
-import { health } from "./http.ts";
+import { echo, health } from "./http.ts";
 
 test("the route answers GET /healthz", async () => {
 	const harness = await testPlugin(health);
@@ -10,3 +11,32 @@ test("the route answers GET /healthz", async () => {
 	expect(await response?.text()).toBe("ok");
 	await harness.stop();
 });
+
+test("the echo route admits a ticket's holder once and echoes what it is sent", async () => {
+	const harness = await testPlugin(echo(new Set(["t-1"])));
+	const websocket = harness.contribution.http?.[0]?.websocket;
+	const refused = await websocket?.accept(
+		new Request("http://localhost/echo?ticket=wrong"),
+	);
+	expect(refused instanceof Response && refused.status).toBe(401);
+	const accepted = await websocket?.accept(
+		new Request("http://localhost/echo?ticket=t-1"),
+	);
+	expect(accepted).toMatchObject({ data: { since: expect.any(Number) } });
+	const replayed = await websocket?.accept(
+		new Request("http://localhost/echo?ticket=t-1"),
+	);
+	expect(replayed instanceof Response && replayed.status).toBe(401);
+	const sent: unknown[] = [];
+	const socket: RouteSocket = {
+		data: undefined,
+		send: (message) => {
+			sent.push(message);
+			return "sent";
+		},
+		close: () => undefined,
+	};
+	await websocket?.message(socket, "hi");
+	expect(sent).toEqual(["hi"]);
+	await harness.stop();
+});

package/examples/http.ts

@@ -15,3 +15,42 @@ export const health = definePlugin({
 		],
 	}),
 });
+
+/**
+ * A route with `websocket` also takes upgrades. The Origin check and `accept` run before any
+ * socket opens, so a browser on another site, or a client without a ticket, never connects.
+ * A ticket opens one socket: `accept` spends it, so one that leaks from a log or the browser's
+ * history opens nothing. Whoever issues the tickets should also let them expire within seconds.
+ */
+export const echo = (tickets: Set<string>) =>
+	definePlugin({
+		name: "echo",
+		setup: () => ({
+			http: [
+				{
+					name: "echo",
+					listener: "public",
+					path: { exact: "/echo" },
+					methods: ["GET"],
+					handle: () => new Response("Upgrade Required", { status: 426 }),
+					websocket: {
+						origins: ["https://chat.example.com"],
+						accept: (request) => {
+							const ticket = URL.parse(request.url)?.searchParams.get("ticket");
+							return ticket && tickets.delete(ticket)
+								? { data: { since: Date.now() } }
+								: new Response("Unauthorized", { status: 401 });
+						},
+						maxMessageBytes: 4096,
+						rate: { messages: 20, perMs: 10_000 },
+						maxBufferedBytes: 64 * 1024,
+						maxConnections: 50,
+						message: (socket, message) => {
+							// "dropped" means the client stopped reading and the host cut it; an echo has nothing to resend.
+							socket.send(message);
+						},
+					},
+				},
+			],
+		}),
+	});

package/examples/prechecks.test.ts

@@ -15,6 +15,7 @@ test("the precheck stays quiet on a normal reading and wakes the agent on a low
 	const context = {
 		schedule: { id: 1, title: "recovery" } as Schedule,
 		firedAt: new Date(),
+		tier: "owner" as const,
 		signal: new AbortController().signal,
 	};
 	expect(await precheck.run(context)).toEqual({