pi-roundtable 0.8.0 → 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/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/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.ts

@@ -22,7 +22,11 @@ export function studyHall(
 ): RoundtableConfig {
 	return {
 		name: "Study Hall",
-		owner: { id: "owner", name: "Ada" },
+		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",

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({

package/examples/principals.test.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "bun:test";
+import { IDENTITY, type Speaker } from "pi-roundtable";
+import { servicePair, testPlugin } from "pi-roundtable/testing";
+import { access, principals } from "./principals.ts";
+
+test("two actor identities of one principal ask about the same person", async () => {
+	const lookedUp: string[] = [];
+	const harness = await testPlugin(principals, {
+		services: [
+			servicePair(IDENTITY, {
+				principal: async (id) => {
+					lookedUp.push(id);
+					return { id, displayName: "Mo", disabled: false };
+				},
+			}),
+		],
+	});
+	try {
+		for (const id of ["discord-actor", "web-actor"]) {
+			const speaker: Speaker = {
+				id,
+				name: "Mo",
+				principalId: "p_mo",
+				tier: "member",
+			};
+			expect(await harness.runTool("principal_who", {}, { speaker })).toBe(
+				"Mo (p_mo)",
+			);
+		}
+		expect(lookedUp).toEqual(["p_mo", "p_mo"]);
+	} finally {
+		await harness.stop();
+	}
+});
+
+test("an unavailable principal is refused even at owner tier", async () => {
+	const harness = await testPlugin(principals, {
+		services: [servicePair(IDENTITY, { principal: async () => undefined })],
+	});
+	try {
+		expect(
+			await harness.runTool(
+				"principal_who",
+				{},
+				{
+					speaker: {
+						id: "actor",
+						name: "Ada",
+						principalId: "operator",
+						tier: "owner",
+					},
+				},
+			),
+		).toContain("This principal is not available.");
+		expect(access.owners[0]?.principal).toBe("operator");
+		expect(access.members.roles).toEqual(["web:role:App.User"]);
+	} finally {
+		await harness.stop();
+	}
+});

package/examples/principals.ts

@@ -0,0 +1,48 @@
+import {
+	type AccessConfig,
+	definePlugin,
+	defineTool,
+	IDENTITY,
+	ToolRefusal,
+} from "pi-roundtable";
+import { Type } from "typebox";
+
+/** One person may have several identities; surface roles never make an owner. */
+export const access = {
+	owners: [
+		{
+			principal: "operator",
+			name: "Ada",
+			identities: ["discord:966666600000000001", "token:remote-mcp"],
+		},
+	],
+	members: { roles: ["web:role:App.User"] },
+	provisioning: "admitted",
+} satisfies AccessConfig;
+
+/** Ask about the current principal, not the external actor or the primary owner. */
+export const principals = definePlugin({
+	name: "principals",
+	requires: [IDENTITY],
+	setup: ({ services }) => {
+		const identity = services.get(IDENTITY);
+		return {
+			tools: [
+				defineTool({
+					name: "principal_who",
+					description: "Show who this turn is for.",
+					parameters: Type.Object({}),
+					minTier: "member",
+					run: async (_args, turn) => {
+						if (!turn.speaker)
+							throw new ToolRefusal("No speaker for this turn.");
+						const person = await identity.principal(turn.speaker.principalId);
+						if (!person || person.disabled)
+							throw new ToolRefusal("This principal is not available.");
+						return `${person.displayName} (${person.id})`;
+					},
+				}),
+			],
+		};
+	},
+});

package/examples/prompt.test.ts

@@ -17,7 +17,7 @@ test("the section names the agent, and the speaker when there is one", async ()
 	expect(
 		section?.build({
 			agent,
-			speaker: { id: "1", name: "Ada", tier: "member" },
+			speaker: { id: "1", name: "Ada", tier: "member", principalId: "1" },
 			scope,
 		}),
 	).toContain("You are talking with Ada.");

package/examples/study-room.test.ts

@@ -1,5 +1,6 @@
 import { expect, test } from "bun:test";
-import { testPlugin } from "pi-roundtable/testing";
+import { IDENTITY } from "pi-roundtable";
+import { servicePair, testPlugin } from "pi-roundtable/testing";
 import { createEchoRuntime } from "./echo-runtime.ts";
 import { FakeSurface } from "./fake-surface.ts";
 import { studyRoom } from "./study-room.ts";
@@ -10,6 +11,16 @@ async function studying() {
 	const harness = await testPlugin(studyRoom, {
 		surfaces: [surface],
 		providers: { runtime: createEchoRuntime },
+		services: [
+			servicePair(IDENTITY, {
+				resolve: async (facts) => ({
+					id: facts.subject,
+					name: facts.name,
+					principalId: "student",
+					tier: "member",
+				}),
+			}),
+		],
 	});
 	return { surface, harness };
 }
@@ -39,6 +50,7 @@ test("a message in a study room runs as a turn of the study kind, with the tutor
 	expect(started?.turn).toMatchObject({
 		kind: "study",
 		channel: "fake:study-algebra",
+		speaker: { principalId: "student", tier: "member" },
 	});
 	expect(started?.turn?.agent).toBeUndefined();
 	await harness.stop();
@@ -60,6 +72,22 @@ test("starting a room over says it was a study conversation", async () => {
 	await harness.stop();
 });
 
+test("an author with no resolved tier never starts a study turn", async () => {
+	const surface = new FakeSurface();
+	const harness = await testPlugin(studyRoom, {
+		surfaces: [surface],
+		providers: { runtime: createEchoRuntime },
+	});
+	try {
+		surface.say("fake:study-algebra", "hello");
+		await Bun.sleep(30);
+		expect(surface.replies).toEqual([]);
+		expect(harness.events).toEqual([]);
+	} finally {
+		await harness.stop();
+	}
+});
+
 test("the persona is the plugin's and belongs to the study kind only", async () => {
 	const { harness } = await studying();
 	const [persona] = harness.contribution.personas ?? [];

package/examples/study-room.ts

@@ -25,25 +25,22 @@ export const studyRoom = definePlugin({
 				priority: 10,
 				// The id of a room starts with `study-`, on whichever surface carries it.
 				owns: (channel) => parseChannelKey(channel).id.startsWith("study-"),
-				admit: (message) =>
-					message.authorIsBot
-						? undefined
-						: {
-								kind: "turn",
-								run: async () => {
-									await turns.run({
-										channel: message.channel,
-										kind: STUDY,
-										text: message.text,
-										speaker: {
-											id: message.authorId,
-											name: message.authorName,
-											tier: "member",
-										},
-									});
-								},
-								failure: "a study turn failed",
-							},
+				admit: (message) => {
+					const speaker = message.speaker;
+					if (message.authorIsBot || !speaker) return undefined;
+					return {
+						kind: "turn",
+						run: async () => {
+							await turns.run({
+								channel: message.channel,
+								kind: STUDY,
+								text: message.text,
+								speaker,
+							});
+						},
+						failure: "a study turn failed",
+					};
+				},
 				// What the conversation was, so a host picks the right persona when it starts over.
 				startFresh: async () => STUDY,
 			},

package/examples/support-desk.test.ts

@@ -2,10 +2,12 @@ import { expect, test } from "bun:test";
 import { testPlugin } from "pi-roundtable/testing";
 import { supportDesk } from "./support-desk.ts";
 
+// A turn runs as its author's principal: here the harness's owner, the one person it knows.
 const turn = (target: string) => ({
 	channel: "support:1" as const,
 	target,
-	author: { id: "u1", name: "Sam" },
+	author: { principalId: "owner", id: "owner", name: "Owner" },
+	tier: "member" as const,
 	turnId: "t1",
 	text: "check the queue",
 });

package/examples/tools.test.ts

@@ -5,7 +5,12 @@ import { notes } from "./tools.ts";
 
 test("note_add saves a note for the speaker and refuses an empty one", async () => {
 	const harness = await testPlugin(notes);
-	const ada: Speaker = { id: "1", name: "Ada", tier: "member" };
+	const ada: Speaker = {
+		id: "1",
+		name: "Ada",
+		tier: "member",
+		principalId: "1",
+	};
 	expect(harness.tools).toEqual(["note_add"]);
 	expect(harness.tiers.minTier("note_add")).toBe("member");
 	expect(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
@@ -26,6 +26,9 @@
 		"src",
 		"!src/**/*.test.ts",
 		"!src/core/testing/file-size.ts",
+		"!src/core/testing/prompt-capture*.ts",
+		"!src/core/testing/fixtures",
+		"!src/prompt-text.snapshot.json",
 		"!src/cli/testing",
 		"templates",
 		"docs",
@@ -52,7 +55,7 @@
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check .",
 		"test": "bun test ./src ./scripts ./examples",
-		"check:packages": "bun run --workspaces typecheck && bun run --workspaces lint && bun run --workspaces test"
+		"check:packages": "bun run --workspaces typecheck && bun run --workspaces lint && bun run --workspaces --sequential test"
 	},
 	"dependencies": {
 		"@babel/parser": "7.29.9",