pi-roundtable 0.7.19 → 0.9.0

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,7 +1,7 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.19",
-	"description": "A plugin-driven Pi agent server for Discord",
+	"version": "0.9.0",
+	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
 	"workspaces": [
@@ -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",
@@ -74,6 +77,7 @@
 		"typescript": "7.0.2",
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
+		"pi-self-compact": "0.2.0",
 		"pi-web-access": "0.35.0"
 	}
 }

package/src/cli/checks/database.ts

@@ -1,3 +1,4 @@
+import type { SQL } from "bun";
 import { nested, openPool, runMigrations } from "../../core/db/migrations.ts";
 import { MigrationError } from "../../core/errors.ts";
 import type { RoundtablePlugin } from "../../core/plugin.ts";
@@ -12,6 +13,8 @@ export interface DatabasePort {
 			| readonly Pick<RoundtablePlugin, "name" | "migrations">[]
 			| undefined,
 	): Promise<void>;
+	/** Runs `use` on a pool of the database at `url`, closed after; `use` only reads. */
+	read<T>(url: string, use: (sql: SQL) => Promise<T>): Promise<T>;
 }
 
 class Rollback extends Error {}
@@ -39,6 +42,14 @@ export const postgres: DatabasePort = {
 			await pool.close();
 		}
 	},
+	async read(url, use) {
+		const pool = openPool(url);
+		try {
+			return await use(pool);
+		} finally {
+			await pool.close();
+		}
+	},
 };
 
 /** The address without its password, safe to print. */

package/src/cli/checks/identity.ts

@@ -0,0 +1,225 @@
+import type { SQL } from "bun";
+import { LEGACY_ACCESS } from "../../core/config/access.ts";
+import type { ResolvedConfig } from "../../core/config/config.ts";
+import type { AccessRules } from "../../core/identity/access-policy.ts";
+import { identityOf, parseIdentity } from "../../core/identity/actor-facts.ts";
+import { declaredConflict } from "../../core/identity/config-owner.ts";
+import { backfillLine } from "../../core/identity/identity-plugin.ts";
+import {
+	type BackfillSummary,
+	backfillPrincipals,
+} from "../../core/identity/identity-schema.ts";
+import {
+	type DeclaredIdentity,
+	declaredIdentities,
+} from "../../core/identity/plugin-identities.ts";
+import { PgPrincipalStore } from "../../core/identity/principal-store.ts";
+import type { Project } from "../project.ts";
+import { fail, ok, type Result, skipped, warn } from "../report.ts";
+import type { DatabasePort } from "./database.ts";
+
+const list = (items: readonly string[]): string =>
+	new Intl.ListFormat("en").format(items);
+
+const message = (error: unknown): string =>
+	error instanceof Error ? error.message : String(error);
+
+/**
+ * The chat surfaces the host talks through, as `everyone` names them: Discord when it is
+ * configured, and each web chat plugin's surface, read from its name (`webchat` is `web`,
+ * `webchat-<surface>` is `<surface>`). A surface another plugin adds at setup is not seen here.
+ */
+export function surfacesOf(
+	config: Pick<ResolvedConfig, "discord">,
+	plugins: readonly { name: string }[],
+): string[] {
+	const surfaces = config.discord ? ["discord"] : [];
+	for (const { name } of plugins) {
+		if (name === "webchat") surfaces.push("web");
+		else if (name.startsWith("webchat-"))
+			surfaces.push(name.slice("webchat-".length));
+	}
+	return surfaces;
+}
+
+/**
+ * Whom the configuration serves: the owners by name, a warning when `everyone: true` admits
+ * everyone on every surface of a host with more than one, and a note when it is written in the
+ * deprecated 0.8 form. It reads no database, so `start` runs it too.
+ */
+export async function checkAccess(project: Project): Promise<Result> {
+	const assembled = await project.assembled();
+	if (!assembled.ok) return skipped("the configuration is not valid yet");
+	const { config, defined } = assembled.value;
+	const surfaces = surfacesOf(config, defined.plugins);
+	const broad = (["admins", "members"] as const).filter(
+		(tier) => config.access[tier]?.everyone === true,
+	);
+	if (broad.length > 0 && surfaces.length > 1)
+		return warn(
+			`${list(broad.map((tier) => `access.${tier}.everyone`))} ${broad.length === 1 ? "is" : "are"} true, which admits everyone on every surface: ${list(surfaces)}.`,
+			`Name the surfaces where everyone may talk, such as everyone: ["discord"], and admit the others by identity or by role, such as roles: ["web:role:<name>"].`,
+		);
+	const owners = config.access.owners;
+	const legacy = config.deprecations.includes(LEGACY_ACCESS)
+		? "; written as the 0.8 owner and speakers, which roundtable upgrade rewrites as access"
+		: "";
+	return ok(
+		`${owners.length} ${owners.length === 1 ? "owner" : "owners"}, ${list(owners.map((owner) => owner.name))}${legacy}`,
+	);
+}
+
+/** What the database says about the configured owners, and what the next start's backfill would make. */
+export interface PrincipalFindings {
+	summary: BackfillSummary;
+	/** A configured owner's identity linked to another principal, which stops the start, and how to fix it. */
+	conflicts: { problem: string; identity: string; fix: string }[];
+	/** Configured owners whose principal is disabled. */
+	disabled: { index: number; id: string; name: string }[];
+	/** Whether any owner, configured or granted by the CLI, can reach the host. */
+	reachable: boolean;
+}
+
+/**
+ * Reads, without writing, what the identity plugin would do at the next start: the backfill as a
+ * dry run, and the configured owners' identity links as its sync checks them. `declaredBy` holds
+ * each identity the plugins declare, with the plugin and the principal it names.
+ */
+export async function principalFindings(
+	sql: SQL,
+	rules: AccessRules,
+	declaredBy: ReadonlyMap<string, DeclaredIdentity> = new Map(),
+): Promise<PrincipalFindings> {
+	const summary = await backfillPrincipals(sql, rules, { dryRun: true });
+	const [tables] = await sql`
+		SELECT to_regclass('principal_identities') IS NOT NULL
+			AND to_regclass('principal_roles') IS NOT NULL AS made`;
+	// Before the first start on 0.9, the start makes every configured owner, enabled.
+	if (tables?.made !== true)
+		return { summary, conflicts: [], disabled: [], reachable: true };
+	const store = await PgPrincipalStore.attach(sql);
+	const conflicts: PrincipalFindings["conflicts"] = [];
+	// The primary owner's principal, undefined when the start makes it.
+	let primary: string | undefined;
+	const disabled: PrincipalFindings["disabled"] = [];
+	let reachable = false;
+	for (const [index, owner] of rules.owners.entries()) {
+		let id = owner.principal;
+		const links = await Promise.all(
+			owner.identities.map(async (identity) => {
+				const ref = parseIdentity(identity);
+				const link = ref && (await store.identity(ref.provider, ref.subject));
+				// A plugin's link no plugin declares any more is unlinked by the start before the owners are synced.
+				return link?.source === "plugin" && !declaredBy.has(identityOf(link))
+					? undefined
+					: link;
+			}),
+		);
+		const unlink = (identity: string) =>
+			`Unlink it with roundtable principal unlink ${identity}, or fix access.owners in roundtable.config.ts`;
+		// As at the start, a plugin's link never tells who the owner is.
+		for (const [i, link] of links.entries()) {
+			if (!link || link.source === "plugin") continue;
+			id ??= link.principalId;
+			const identity = owner.identities[i] ?? "";
+			if (link.principalId !== id)
+				conflicts.push({
+					problem: `access.owners[${index}].identities[${i}]: ${identity} is linked to principal ${link.principalId}, not to this owner's ${id}`,
+					identity,
+					fix: unlink(identity),
+				});
+		}
+		// As at the start, an identity a plugin declares is bound to this owner on this start, or it stops it.
+		for (const [i, identity] of owner.identities.entries()) {
+			const ref = parseIdentity(identity);
+			const declared = ref && declaredBy.get(identityOf(ref));
+			if (!declared) continue;
+			const conflict = declaredConflict({
+				index,
+				i,
+				identity,
+				id,
+				link: links[i],
+				declared,
+				primary,
+				first: index === 0,
+			});
+			if (conflict) conflicts.push({ ...conflict, identity });
+		}
+		if (index === 0) primary = id;
+		const principal = id === undefined ? undefined : await store.get(id);
+		if (principal?.disabled)
+			disabled.push({ index, id: principal.id, name: owner.name });
+		else reachable = true;
+	}
+	for (const holder of await store.holders("owner"))
+		if (
+			holder.source === "cli" &&
+			(await store.get(holder.principalId))?.disabled === false
+		)
+			reachable = true;
+	return { summary, conflicts, disabled, reachable };
+}
+
+/**
+ * The principals the next start would make from the people 0.8 stored, as a dry run printed as the
+ * start logs it; a configured owner's identity linked to another principal, which stops the
+ * start; and a disabled configured owner, or no owner left who can reach the host.
+ */
+export async function checkPrincipals(
+	project: Project,
+	database: DatabasePort,
+): Promise<Result> {
+	const url = await project.text("database", "url");
+	if (!url) return skipped("database.url has no value");
+	const assembled = await project.assembled();
+	if (!assembled.ok) return skipped("the configuration is not valid yet");
+	const rules = assembled.value.config.access;
+	let declaredBy: Map<string, DeclaredIdentity>;
+	try {
+		declaredBy = new Map(
+			declaredIdentities(assembled.value.defined.plugins).map((declared) => [
+				declared.identity,
+				declared,
+			]),
+		);
+	} catch (error) {
+		return skipped(
+			`the plugins' identities are not valid yet (${message(error)})`,
+		);
+	}
+	let findings: PrincipalFindings;
+	try {
+		findings = await database.read(url, (sql) =>
+			principalFindings(sql, rules, declaredBy),
+		);
+	} catch (error) {
+		return skipped(`PostgreSQL did not answer (${message(error)})`);
+	}
+	const dryRun = `dry run, nothing written: ${backfillLine(findings.summary)}`;
+	if (findings.conflicts.length > 0)
+		return fail(
+			`${findings.conflicts.map((conflict) => conflict.problem).join("; ")}; the host does not start until this is fixed.`,
+			findings.conflicts.map((conflict) => conflict.fix).join("\n"),
+		);
+	if (findings.disabled.length > 0) {
+		const who = list(
+			findings.disabled.map(
+				(owner) =>
+					`access.owners[${owner.index}] ${owner.name} (principal ${owner.id})`,
+			),
+		);
+		return warn(
+			findings.reachable
+				? `${who} ${findings.disabled.length === 1 ? "is" : "are"} disabled, so the host does not serve them.`
+				: `no owner can reach the host: ${who} ${findings.disabled.length === 1 ? "is" : "are"} disabled.`,
+			[
+				...findings.disabled.map(
+					(owner) => `Enable with roundtable principal enable ${owner.id}`,
+				),
+				dryRun,
+			].join("\n"),
+		);
+	}
+	return ok(dryRun);
+}

package/src/cli/checks/model.ts

@@ -1,8 +1,17 @@
 import { parseModelRef } from "../../core/models.ts";
+import {
+	BRIDGE_MEMORY_FIX,
+	bridgeMemoryProblem,
+	configuredCrowd,
+	onClaudeBridge,
+} from "../../core/runtime/bridge-guard.ts";
 import type { Ports, Project } from "../project.ts";
-import { fail, ok, type Result, skipped } from "../report.ts";
+import { fail, ok, type Result, skipped, warn } from "../report.ts";
 
-/** A login exists for the provider of the configured model: an API key variable or a stored login. */
+/**
+ * A login exists for the provider of the configured model: an API key variable or a stored login;
+ * with a non-failing warning for bridge's shared private-memory replay risk.
+ */
 export async function checkModelLogin(
 	project: Project,
 	ports: Pick<Ports, "login">,
@@ -15,12 +24,21 @@ export async function checkModelLogin(
 			`the model ${JSON.stringify(model)} is not written <provider>/<id>.`,
 			"Write it like anthropic/claude-sonnet-5-5 in MODEL in .env.",
 		);
+	// Admission warns of risk; each shared turn checks actual private history.
+	let risk: Result | undefined;
+	const assembled = await project.assembled();
+	if (assembled.ok) {
+		const { config } = assembled.value;
+		const crowd = configuredCrowd(config.access, config.plugins);
+		if (config.memory && crowd && onClaudeBridge(ref))
+			risk = warn(bridgeMemoryProblem(model, crowd), BRIDGE_MEMORY_FIX);
+	}
 	const dir = await project.text("agentDir");
 	const dataDir = await project.text("dataDir");
 	const agentDir = dir ?? (dataDir ? `${dataDir}/pi` : undefined);
 	if (!agentDir) return skipped("dataDir has no value");
 	const source = await ports.login(agentDir, ref.provider);
-	if (source) return ok(`${ref.provider} login from ${source}`);
+	if (source) return risk ?? ok(`${ref.provider} login from ${source}`);
 	return fail(
 		`no login for ${ref.provider}, the provider of ${model}.`,
 		`Set the provider's API key in .env (ANTHROPIC_API_KEY for anthropic, OPENAI_API_KEY for openai), or sign in with Pi so ${agentDir}/auth.json holds it.`,