pi-roundtable 0.7.18 → 0.8.0

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,31 @@
+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",
+		owner: { id: "owner", name: "Ada" },
+		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/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.18",
-	"description": "A plugin-driven Pi agent server for Discord",
+	"version": "0.8.0",
+	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
 	"workspaces": [
@@ -74,6 +74,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/cli.ts

@@ -14,7 +14,7 @@ import { loadConfigFile, type Ports } from "./project.ts";
 import { formatOutcomes } from "./report.ts";
 import { assemble, providerLogin } from "./runtime.ts";
 import { start } from "./start.ts";
-import { OFFICIAL_PLUGINS } from "./templates.ts";
+import { ADAPTERS, isAdapter, OFFICIAL_PLUGINS } from "./templates.ts";
 
 /** What the command line reads from its surroundings; tests replace every part. */
 export interface CliEnvironment {
@@ -32,7 +32,9 @@ export interface CliEnvironment {
 
 const USAGE = `roundtable: a Discord agent server on Pi
 
-  roundtable init [dir]         create a project (default: the current directory)
+  roundtable init [dir] [--adapter discord|web]
+                                create a project (default: the current directory) that talks
+                                through Discord (the default) or through the web chat
   roundtable doctor [--reachable]  check the setup and say how to fix what is wrong
   roundtable start              run the checks that need no network, then the bot
   roundtable add plugin <name>  add plugins/<name>.ts and its test, and list it in the config
@@ -108,13 +110,22 @@ export async function runCli(
 		return 0;
 	}
 	if (command === "init") {
-		const [dir, ...extra] = rest;
-		if (extra.length > 0) return usage(io, "init takes at most one directory");
+		const at = rest.indexOf("--adapter");
+		const adapter = at === -1 ? "discord" : rest[at + 1];
+		if (adapter === undefined || !isAdapter(adapter))
+			return usage(
+				io,
+				`--adapter takes one of ${ADAPTERS.join(", ")}, not ${JSON.stringify(adapter ?? "")}`,
+			);
+		const [dir, ...extra] = at === -1 ? rest : rest.toSpliced(at, 2);
+		if (extra.length > 0 || dir?.startsWith("-"))
+			return usage(io, "init takes at most one directory");
 		const report = init({
 			cwd: io.cwd,
 			...(dir === undefined ? {} : { dir }),
 			bun: io.bun(),
 			version: io.version(),
+			adapter,
 		});
 		if (!report.ok) {
 			for (const line of report.problems) io.err(line);

package/src/cli/doctor.ts

@@ -14,7 +14,14 @@ import { checkModelLogin } from "./checks/model.ts";
 import { checkPublicUrl } from "./checks/public-url.ts";
 import type { Http } from "./http.ts";
 import { type Ports, Project } from "./project.ts";
-import { type Check, failed, type Outcome, runChecks } from "./report.ts";
+import {
+	type Check,
+	failed,
+	type Outcome,
+	type Result,
+	runChecks,
+	skipped,
+} from "./report.ts";
 
 export interface DoctorInputs {
 	cwd: string;
@@ -39,6 +46,11 @@ export function buildChecks(
 ): Check[] {
 	const { cwd, env, bun, ports, database, http, reachable } = inputs;
 	const discord = new Discord(project, http);
+	// A project without Discord asks Discord nothing.
+	const ifDiscord = (run: () => Promise<Result>) => async (): Promise<Result> =>
+		(await project.leavesOut("discord"))
+			? skipped("no Discord is configured")
+			: run();
 	return [
 		{ name: "Bun", offline: true, run: async () => checkBun(bun) },
 		{
@@ -62,21 +74,25 @@ export function buildChecks(
 			offline: false,
 			run: () => checkDatabase(project, database),
 		},
-		{ name: "Discord token", offline: false, run: () => checkToken(discord) },
+		{
+			name: "Discord token",
+			offline: false,
+			run: ifDiscord(() => checkToken(discord)),
+		},
 		{
 			name: "Discord guild",
 			offline: false,
-			run: () => checkGuild(project, discord),
+			run: ifDiscord(() => checkGuild(project, discord)),
 		},
 		{
 			name: "Discord intents",
 			offline: false,
-			run: () => checkIntents(discord),
+			run: ifDiscord(() => checkIntents(discord)),
 		},
 		{
 			name: "Discord channel",
 			offline: false,
-			run: () => checkChannel(project, discord),
+			run: ifDiscord(() => checkChannel(project, discord)),
 		},
 		{
 			name: "model login",

package/src/cli/init.ts

@@ -1,7 +1,12 @@
 import { existsSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
 import { type BunFacts, checkBun } from "./checks/bun.ts";
-import { type Rendered, renderProject, writeRendered } from "./templates.ts";
+import {
+	type Adapter,
+	type Rendered,
+	renderProject,
+	writeRendered,
+} from "./templates.ts";
 
 export interface InitInputs {
 	cwd: string;
@@ -12,6 +17,8 @@ export interface InitInputs {
 	version: string;
 	/** Where the templates are; default the package's own. */
 	templates?: string;
+	/** The chat network the project talks through; default Discord. */
+	adapter?: Adapter;
 }
 
 export interface InitReport {
@@ -61,6 +68,7 @@ export function init(inputs: InitInputs): InitReport {
 	const files: Rendered[] = renderProject(
 		{ project: projectName(root), version: inputs.version },
 		inputs.templates,
+		inputs.adapter,
 	);
 	const existing = files
 		.map((file) => file.path)

package/src/cli/project.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { liftAdapters } from "../core/config/adapters.ts";
 import {
 	type ResolvedConfig,
 	type RoundtableConfig,
@@ -51,6 +52,16 @@ export interface Assembled {
 const message = (error: unknown): string =>
 	error instanceof Error ? error.message : String(error);
 
+/** The configuration with its adapters lifted, or as written when they cannot be. */
+// pi-lens-ignore: no-unknown-returns — the configuration as written is untyped until the schema checks it
+function lifted(value: unknown): unknown {
+	try {
+		return liftAdapters(value);
+	} catch {
+		return value;
+	}
+}
+
 /**
  * The project's configuration, loaded and resolved at most once and shared by every check, so a
  * mistake in it is reported by the configuration check and the checks that need it say so
@@ -67,10 +78,14 @@ export class Project {
 		this.#ports = ports;
 	}
 
-	/** The exported value as written, before the schema looks at it. */
+	/**
+	 * The exported value as written, before the schema looks at it, with its adapters' settings in
+	 * the places the host reads them, such as a Discord adapter's as `discord`. Adapters it cannot
+	 * read stay as written; the configuration check reports them.
+	 */
 	raw(): Promise<Loaded<unknown>> {
 		this.#raw ??= this.#ports.loadConfig(this.#cwd).then(
-			(value): Loaded<unknown> => ({ ok: true, value }),
+			(value): Loaded<unknown> => ({ ok: true, value: lifted(value) }),
 			(error: unknown): Loaded<unknown> => ({
 				ok: false,
 				failure: fail(
@@ -96,6 +111,17 @@ export class Project {
 		return typeof value === "string" && value.trim() !== "" ? value : undefined;
 	}
 
+	/** Whether the configuration, loaded, leaves the top-level key out; false when it could not be loaded. */
+	async leavesOut(key: string): Promise<boolean> {
+		const raw = await this.raw();
+		return (
+			raw.ok &&
+			typeof raw.value === "object" &&
+			raw.value !== null &&
+			(raw.value as Record<string, unknown>)[key] === undefined
+		);
+	}
+
 	/** The configuration checked against its schema and assembled, or the failure that says why not. */
 	assembled(): Promise<Loaded<Assembled>> {
 		this.#assembled ??= this.#assemble();

package/src/cli/templates.ts

@@ -19,6 +19,23 @@ const OFFICIAL_DIR = "official";
 /** The directory of the plugin `add package` writes around a Pi package. */
 const PACKAGE_DIR = "package";
 
+/** The directory of each chat network's files that replace or add to the skeleton's, one directory per adapter. */
+const ADAPTERS_DIR = "adapters";
+
+/** The chat networks `init` can set a project up for; Discord's files are the skeleton itself. */
+export const ADAPTERS = ["discord", "web"] as const;
+export type Adapter = (typeof ADAPTERS)[number];
+
+/** Whether `name` is an adapter `init` knows. */
+export const isAdapter = (name: string): name is Adapter =>
+	(ADAPTERS as readonly string[]).includes(name);
+
+/** Skeleton files a project for the adapter leaves out: a web project has no agents and no shared persona. */
+const LEFT_OUT: Readonly<Record<Adapter, readonly string[]>> = {
+	discord: [],
+	web: ["agents.ts", "persona/shared.md"],
+};
+
 /** The plugins the package ships ready-made: `add plugin <name>` copies these instead of the `hello` template, so the names are reserved. */
 export const OFFICIAL_PLUGINS = [
 	"codex-images",
@@ -143,31 +160,46 @@ export function renderPackagePlugin(
 	}));
 }
 
-/** Every file of a new project: the skeleton and the `hello` plugin, paths relative to the project. */
+/**
+ * Every file of a new project for `adapter` (default Discord): the skeleton, without the files the
+ * adapter leaves out and with its own files in place of the skeleton's, and the `hello` plugin;
+ * paths relative to the project.
+ */
 export function renderProject(
 	substitutions: Substitutions,
 	dir = TEMPLATES_DIR,
+	adapter: Adapter = "discord",
 ): Rendered[] {
 	if (!existsSync(dir)) throw new Error(`templates are missing: ${dir}`);
 	const values = {
 		PROJECT: substitutions.project,
 		VERSION: substitutions.version,
 	};
+	const render = (base: string, path: string): Rendered => ({
+		path: targetOf(path),
+		content: fill(readFileSync(join(base, path), "utf8"), values),
+	});
+	const overlayDir = join(dir, ADAPTERS_DIR, adapter);
+	const overlay = existsSync(overlayDir)
+		? filesUnder(overlayDir).map((file) =>
+				render(overlayDir, relative(overlayDir, file)),
+			)
+		: [];
+	const replaced = new Set([
+		...LEFT_OUT[adapter],
+		...overlay.map((file) => file.path),
+	]);
 	const skeleton = filesUnder(dir)
 		.map((file) => relative(dir, file))
-		.flatMap((path) =>
-			[PLUGIN_DIR, OFFICIAL_DIR, PACKAGE_DIR].some((sub) =>
-				path.startsWith(`${sub}/`),
-			)
-				? []
-				: [
-						{
-							path: targetOf(path),
-							content: fill(readFileSync(join(dir, path), "utf8"), values),
-						},
-					],
-		);
-	return [...skeleton, ...renderPlugin(pluginNames("hello"), dir)];
+		.filter(
+			(path) =>
+				![PLUGIN_DIR, OFFICIAL_DIR, PACKAGE_DIR, ADAPTERS_DIR].some((sub) =>
+					path.startsWith(`${sub}/`),
+				),
+		)
+		.map((path) => render(dir, path))
+		.filter((file) => !replaced.has(file.path));
+	return [...skeleton, ...overlay, ...renderPlugin(pluginNames("hello"), dir)];
 }
 
 /** Writes rendered files under `root`, creating directories; the caller has checked that none exists. */

package/src/core/agents/agent-team-fixture.ts

@@ -25,6 +25,7 @@ import {
 } from "../testing/database.ts";
 import { useTestLocale } from "../testing/locale.ts";
 import { OWNER_SPEAKER, TEST_OWNER } from "../testing/owner.ts";
+import { toolTiers } from "../tool-tiers.ts";
 import type {
 	AgentCategory,
 	AgentChannels,
@@ -176,6 +177,10 @@ export interface TeamFixture {
 	skills: SkillRegistry;
 }
 
+/** The tool tiers the team reads; `deploy` is an admin's tool, so an admin may approve it. */
+const FIXTURE_TIERS = toolTiers();
+FIXTURE_TIERS.declare("test", { deploy: "admin" });
+
 /** The fixture of the running test; set by `useTeamFixture` before each test. */
 export const fx = {} as TeamFixture;
 
@@ -297,6 +302,7 @@ export function useTeamFixture(): void {
 		eventLog.length = 0;
 		team = new AgentTeam({
 			owner: TEST_OWNER,
+			toolTiers: FIXTURE_TIERS,
 			shellUser: "mcops",
 			guildId: "1",
 			entryChannelId: ENTRY,

package/src/core/agents/team-turns.ts

@@ -143,8 +143,13 @@ export class TeamTurns {
 		);
 	}
 
-	/** Whether the speaker's tier holds every tool of the held actions. */
+	/**
+	 * Whether the speaker may approve the held actions: the owner, or the speaker whose turn held
+	 * them, when their tier now holds every tool. Nobody else in the channel may.
+	 */
 	#mayApprove(speaker: Speaker, pending: PendingConfirmation): boolean {
+		if (speaker.tier !== "owner" && speaker.id !== pending.speakerId)
+			return false;
 		const tiers = this.#options.toolTiers ?? toolTiers();
 		return pending.calls.every(
 			(call) =>