pi-roundtable 0.7.18 → 0.8.0

package/src/core/testing/surface-contract.ts

@@ -0,0 +1,383 @@
+import { describe, test } from "bun:test";
+import type { InboundMessage } from "../contract/channels.ts";
+import type { ChatSurface } from "../contract/surface.ts";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { Approval } from "../domain/owner-prompts.ts";
+import type { TurnProgress } from "../domain/progress.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+
+/** What the person on a surface's network has seen, as the contract reads it. */
+export type SurfaceObservation =
+	| { kind: "reply"; text: string; files: readonly string[] }
+	| { kind: "typing"; on: boolean }
+	| { kind: "stop"; on: boolean }
+	| { kind: "progress"; event: TurnProgress }
+	| { kind: "prompt"; id: string; title: string }
+	| { kind: "prompt_closed"; id: string };
+
+/**
+ * A surface under the contract, and one person on its network the contract acts as. The
+ * contract starts the surface, then calls `join`; it stops the surface after `close`.
+ */
+export interface SurfaceContractSubject {
+	surface: ChatSurface;
+	/** A channel of the surface the person takes part in. */
+	channel: ChannelKey;
+	/** The person joins `channel`, once the surface has started. */
+	join?(): Promise<void>;
+	/** The person writes `text` in `channel`; the surface delivers it to the host. */
+	write(text: string): Promise<void>;
+	/** Everything the person has seen so far, oldest first. */
+	observations(): readonly SurfaceObservation[];
+	/** The person answers an open approval; without it the prompt checks are skipped. */
+	answer?(prompt: string, approved: boolean): Promise<void>;
+	/**
+	 * The person as the speaker of the turns that ask them, given to `surface.prompts`; default an
+	 * owner-tier speaker. Every approval the contract asks for needs exactly the speaker's tier, so
+	 * it is theirs to answer.
+	 */
+	speaker?: Speaker;
+	/**
+	 * Someone else on the surface's network, not the owner, who knows the id of the person's open
+	 * prompt and answers it; without it the responder-scope check is skipped.
+	 */
+	stranger?: {
+		/** They join the surface, once it has started. */
+		join?(): Promise<void>;
+		answer(prompt: string, approved: boolean): Promise<void>;
+	};
+	close?(): Promise<void>;
+}
+
+/** One way the subject broke the contract. */
+export interface SurfaceContractFailure {
+	name: string;
+	error: unknown;
+}
+
+interface Running {
+	subject: SurfaceContractSubject;
+	delivered: InboundMessage[];
+}
+
+interface Check {
+	name: string;
+	/** Whether the check applies to this subject; a check that does not is skipped. */
+	applies?(subject: SurfaceContractSubject): boolean;
+	run(running: Running): Promise<void>;
+}
+
+class ContractBroken extends Error {
+	override name = "ContractBroken";
+}
+
+function expectThat(condition: boolean, message: string): void {
+	if (!condition) throw new ContractBroken(message);
+}
+
+async function until(
+	done: () => boolean,
+	what: string,
+	ms = 2000,
+): Promise<void> {
+	const deadline = Date.now() + ms;
+	while (!done()) {
+		if (Date.now() > deadline)
+			throw new ContractBroken(`timed out waiting until ${what}`);
+		await Bun.sleep(5);
+	}
+}
+
+const seen = (running: Running, kind: SurfaceObservation["kind"]) =>
+	running.subject.observations().filter((o) => o.kind === kind);
+
+const speakerOf = (subject: SurfaceContractSubject): Speaker =>
+	subject.speaker ?? { id: "contract-speaker", name: "Ada", tier: "owner" };
+
+/** The newest prompt the person has seen, once one more than `before` is open. */
+async function nextPrompt(running: Running, before: number): Promise<string> {
+	await until(
+		() => seen(running, "prompt").length > before,
+		"the person sees the approval",
+	);
+	const prompt = seen(running, "prompt").at(-1);
+	if (prompt?.kind !== "prompt") throw new ContractBroken("no prompt seen");
+	return prompt.id;
+}
+
+/** Asks for one approval and answers it as the person does. */
+async function approval(running: Running, approved: boolean) {
+	const { surface, channel, answer } = running.subject;
+	const prompts = surface.prompts?.(channel, speakerOf(running.subject));
+	if (!prompts || !answer)
+		throw new ContractBroken("the surface shows no prompts");
+	const before = seen(running, "prompt").length;
+	const result = prompts.confirm(
+		"Approve?",
+		"Send the report.",
+		undefined,
+		speakerOf(running.subject).tier,
+	);
+	await answer(await nextPrompt(running, before), approved);
+	return result;
+}
+
+const CHECKS: readonly Check[] = [
+	{
+		name: "names a surface prefix without a colon, and owns the subject's channel",
+		run: async ({ subject }) => {
+			const { surface } = subject.surface;
+			expectThat(
+				surface !== "" && !surface.includes(":"),
+				`"${surface}" is not a surface name`,
+			);
+			expectThat(
+				parseChannelKey(subject.channel).surface === surface,
+				`${subject.channel} is not a channel of ${surface}`,
+			);
+		},
+	},
+	{
+		name: "delivers what the person writes, in their channel",
+		run: async (running) => {
+			await running.subject.write("hello from the contract");
+			await until(
+				() => running.delivered.length > 0,
+				"the surface delivers the message",
+			);
+			const [message] = running.delivered;
+			expectThat(
+				message?.channel === running.subject.channel,
+				`delivered to ${message?.channel}, not ${running.subject.channel}`,
+			);
+			expectThat(
+				message?.text === "hello from the contract",
+				`delivered the text ${JSON.stringify(message?.text)}`,
+			);
+			expectThat(
+				Boolean(message?.messageId) && Boolean(message?.authorId),
+				"a delivered message names its id and its author",
+			);
+			expectThat(message?.authorIsBot === false, "the person is not a bot");
+		},
+	},
+	{
+		name: "shows the person every chunk of a reply",
+		run: async (running) => {
+			const { surface, channel } = running.subject;
+			await surface.sendReply(channel, { chunks: ["first part", "second"] });
+			await until(
+				() => seen(running, "reply").length > 0,
+				"the person sees the reply",
+			);
+			const reply = seen(running, "reply")[0];
+			expectThat(
+				reply?.kind === "reply" &&
+					reply.text.includes("first part") &&
+					reply.text.includes("second"),
+				"the reply shows both chunks",
+			);
+		},
+	},
+	{
+		name: "delivers a reply's files when it supports them",
+		applies: (subject) => subject.surface.supportsFiles === true,
+		run: async (running) => {
+			const { surface, channel } = running.subject;
+			await surface.sendReply(channel, {
+				chunks: ["see the file"],
+				files: [{ name: "notes.txt", data: new TextEncoder().encode("hi") }],
+			});
+			await until(
+				() =>
+					seen(running, "reply").some(
+						(o) => o.kind === "reply" && o.files.includes("notes.txt"),
+					),
+				"the person receives the file",
+			);
+		},
+	},
+	{
+		name: "a typing indicator ends when its handle is called, and calling it again is harmless",
+		applies: (subject) => subject.surface.startTyping !== undefined,
+		run: async (running) => {
+			const { surface, channel } = running.subject;
+			const stop = surface.startTyping?.(channel);
+			stop?.();
+			stop?.();
+			await until(
+				() => seen(running, "typing").some((o) => o.kind === "typing" && !o.on),
+				"the person sees typing end",
+			);
+		},
+	},
+	{
+		name: "a stop control ends when its handle is called, and calling it again is harmless",
+		applies: (subject) => subject.surface.showStop !== undefined,
+		run: async (running) => {
+			const { surface, channel } = running.subject;
+			const hide = surface.showStop?.(channel);
+			hide?.();
+			hide?.();
+			await until(
+				() => seen(running, "stop").some((o) => o.kind === "stop" && !o.on),
+				"the person sees the stop control go",
+			);
+		},
+	},
+	{
+		name: "shows a running turn's progress",
+		applies: (subject) => subject.surface.progress !== undefined,
+		run: async (running) => {
+			const { surface, channel } = running.subject;
+			await surface.progress?.(channel, { type: "text", delta: "Look" });
+			await surface.progress?.(channel, {
+				type: "tool_start",
+				id: "t1",
+				tool: "search",
+			});
+			await until(
+				() => seen(running, "progress").length >= 2,
+				"the person sees the progress",
+			);
+		},
+	},
+	{
+		name: "an approval resolves as the person answers it, and closes",
+		applies: (subject) =>
+			subject.surface.prompts !== undefined && subject.answer !== undefined,
+		run: async (running) => {
+			const approved = await approval(running, true);
+			expectThat(approved === "approved", `approving answered ${approved}`);
+			const declined = await approval(running, false);
+			expectThat(declined === "declined", `declining answered ${declined}`);
+			await until(
+				() => seen(running, "prompt_closed").length >= 2,
+				"both approvals close",
+			);
+		},
+	},
+	{
+		name: "a stopped turn's approval resolves cancelled and closes",
+		applies: (subject) =>
+			subject.surface.prompts !== undefined && subject.answer !== undefined,
+		run: async (running) => {
+			const { surface, channel } = running.subject;
+			const prompts = surface.prompts?.(channel, speakerOf(running.subject));
+			if (!prompts) throw new ContractBroken("the surface shows no prompts");
+			const stop = new AbortController();
+			const before = seen(running, "prompt").length;
+			const result = prompts.confirm(
+				"Approve?",
+				"Send it.",
+				stop.signal,
+				speakerOf(running.subject).tier,
+			);
+			const id = await nextPrompt(running, before);
+			stop.abort();
+			const answer: Approval = await result;
+			expectThat(answer === "cancelled", `a stopped turn answered ${answer}`);
+			await until(
+				() =>
+					seen(running, "prompt_closed").some(
+						(o) => o.kind === "prompt_closed" && o.id === id,
+					),
+				"the stopped approval closes",
+			);
+		},
+	},
+	{
+		name: "another person cannot answer the person's approval",
+		applies: (subject) =>
+			subject.surface.prompts !== undefined &&
+			subject.answer !== undefined &&
+			subject.stranger !== undefined,
+		run: async (running) => {
+			const { surface, channel, answer, stranger } = running.subject;
+			const prompts = surface.prompts?.(channel, speakerOf(running.subject));
+			if (!prompts || !answer || !stranger)
+				throw new ContractBroken("the surface shows no prompts");
+			await stranger.join?.();
+			const before = seen(running, "prompt").length;
+			let settled: Approval | undefined;
+			const result = prompts
+				.confirm(
+					"Approve?",
+					"Send the report.",
+					undefined,
+					speakerOf(running.subject).tier,
+				)
+				.then((value) => {
+					settled = value;
+					return value;
+				});
+			const id = await nextPrompt(running, before);
+			await stranger.answer(id, true);
+			await Bun.sleep(50);
+			expectThat(
+				settled === undefined,
+				`another person's answer settled the approval as ${settled}`,
+			);
+			await answer(id, false);
+			const own = await result;
+			expectThat(own === "declined", `the person's answer came back ${own}`);
+		},
+	},
+];
+
+async function runCheck(
+	check: Check,
+	make: () => Promise<SurfaceContractSubject>,
+): Promise<"passed" | "skipped"> {
+	const subject = await make();
+	const running: Running = { subject, delivered: [] };
+	try {
+		if (check.applies && !check.applies(subject)) return "skipped";
+		await subject.surface.start((message) => running.delivered.push(message));
+		await subject.join?.();
+		await check.run(running);
+		return "passed";
+	} finally {
+		await subject.close?.();
+		await subject.surface.stop?.();
+	}
+}
+
+/**
+ * Runs the chat surface contract on fresh subjects from `make`, one per check, and returns the
+ * checks the surface broke. `describeSurfaceContract` registers the same checks as tests.
+ */
+export async function checkSurfaceContract(
+	make: () => Promise<SurfaceContractSubject>,
+): Promise<SurfaceContractFailure[]> {
+	const failures: SurfaceContractFailure[] = [];
+	for (const check of CHECKS) {
+		try {
+			await runCheck(check, make);
+		} catch (error) {
+			failures.push({ name: check.name, error });
+		}
+	}
+	return failures;
+}
+
+/**
+ * Registers the chat surface contract as one test per check, under `name`: the surface names a
+ * prefix and owns its channel, delivers what its person writes, shows every chunk of a reply, and,
+ * where it offers them, delivers files, ends typing and stop controls idempotently, shows
+ * progress, resolves approvals as the person answers or as a stopped turn cancels them, and
+ * ignores another person's answer to the person's approval. Each
+ * check gets a fresh subject from `make`; a check for an optional part the surface lacks passes.
+ */
+export function describeSurfaceContract(
+	name: string,
+	make: () => Promise<SurfaceContractSubject>,
+): void {
+	describe(`${name} keeps the chat surface contract`, () => {
+		for (const check of CHECKS)
+			test(check.name, async () => {
+				await runCheck(check, make);
+			});
+	});
+}

package/src/core/testing/test-host.ts

@@ -43,8 +43,13 @@ export interface TestHostOptions {
 	 * having none, whatever login the machine holds.
 	 */
 	apiKeys?: Readonly<Record<string, string>>;
-	/** What the stand-in Discord hands out. */
-	discord?: Partial<Pick<DiscordConnection, "agentChannels" | "ownerChannel">>;
+	/**
+	 * What the stand-in Discord hands out. `false` boots a host without Discord: no `discord`,
+	 * `http`, or `agents` in the configuration, so no Discord plugin and no agent server.
+	 */
+	discord?:
+		| false
+		| Partial<Pick<DiscordConnection, "agentChannels" | "ownerChannel">>;
 }
 
 export interface TestHost {
@@ -68,8 +73,15 @@ export interface TestHost {
 	stop(): Promise<void>;
 }
 
-function defaultConfig(): RoundtableConfig {
+function defaultConfig(withDiscord: boolean): RoundtableConfig {
 	const dataDir = mkdtempSync(join(tmpdir(), "roundtable-test-host-"));
+	if (!withDiscord)
+		return {
+			owner: { id: "100000000000000001", name: "Ada" },
+			database: { url: testDatabaseUrl },
+			dataDir,
+			model: "anthropic/claude-sonnet-5-5",
+		};
 	return {
 		owner: { id: "100000000000000001", name: "Ada" },
 		discord: {
@@ -197,14 +209,19 @@ export async function testHost(
 			return { services: [{ name: "probe" }] };
 		},
 	};
-	const base: RoundtableConfig = { ...defaultConfig(), ...options.config };
+	const withDiscord = options.discord !== false;
+	const given = options.discord === false ? undefined : options.discord;
+	const base: RoundtableConfig = {
+		...defaultConfig(withDiscord),
+		...options.config,
+	};
 	const resolved = resolveConfig(base);
-	const { rootCommand } = resolved.discord;
+	const rootCommand = resolved.slug;
 	const guard = new OwnerGuard(resolved.owner.id, silentLogger(), rootCommand);
 	const config: RoundtableConfig = {
 		...base,
 		plugins: [
-			standInDiscord(commands, guard, options.discord),
+			...(withDiscord ? [standInDiscord(commands, guard, given)] : []),
 			{
 				name: "test-runtime",
 				providers: { runtime: () => runtime },
@@ -227,9 +244,10 @@ export async function testHost(
 	await roundtable.run();
 	if (!captured) throw new Error("the probe was not set up");
 	const context = captured;
-	const ownerChannel = await (
-		options.discord?.ownerChannel ?? (async () => "discord:owner-dm" as const)
-	)();
+	// Without Discord the owner's session is a conversation of a plugin's surface.
+	const ownerChannel = withDiscord
+		? await (given?.ownerChannel ?? (async () => "discord:owner-dm" as const))()
+		: ("test:owner" as const);
 	/** A group seat's turns run in the group's channel; an agent's in its own. */
 	const turnChannelOf = (scope?: AgentTurnScope) =>
 		scope?.group ? scope.session : scope?.home;

package/src/discord/index.ts

@@ -3,6 +3,7 @@
 
 export type { DiscordServices } from "../core/builtin/discord.ts";
 export { DISCORD } from "../core/builtin/discord.ts";
+export type { DiscordAdapterConfig } from "../core/config/config.ts";
 export type { AgentPanelMessage } from "../core/discord/agent-commands.ts";
 export type {
 	AgentPanel,
@@ -33,6 +34,7 @@ export type {
 	ChannelInfo,
 	DiscordConnection,
 } from "../core/discord/connection.ts";
+export { discord } from "../core/discord/discord-adapter.ts";
 export type {
 	CommandGuard,
 	CommandRegistrar,

package/src/index.ts

@@ -21,6 +21,8 @@ export {
 	AGENT_TEAM_SERVICE,
 } from "./core/builtin/agent-server.ts";
 export type {
+	AdapterConfig,
+	DiscordConfig,
 	Pronouns,
 	RoundtableConfig,
 	TierConfig,
@@ -57,6 +59,12 @@ export type { ServiceKey, Services } from "./core/contract/services.ts";
 export { serviceKey } from "./core/contract/services.ts";
 export type { ChatSurface, SurfacePort } from "./core/contract/surface.ts";
 export { channelKey, parseChannelKey } from "./core/contract/surface.ts";
+export type {
+	ConversationRecord,
+	ConversationRegistration,
+	ConversationRegistry,
+	ConversationVisibility,
+} from "./core/conversations/conversation-registry.ts";
 export type { Migration, MigrationReport } from "./core/db/migrations.ts";
 export { migrateDatabase } from "./core/db/migrations.ts";
 export type { ToolContribution, ToolSpec, ToolTurn } from "./core/define.ts";
@@ -101,6 +109,7 @@ export type {
 	OwnerQuestion,
 } from "./core/domain/owner-prompts.ts";
 export type { TurnRequest } from "./core/domain/ports.ts";
+export type { TurnProgress } from "./core/domain/progress.ts";
 export type { DrainOptions } from "./core/drain.ts";
 export {
 	JudgeError,
@@ -117,6 +126,12 @@ export type {
 	ListenerAddress,
 	ListenerConfig,
 } from "./core/http/listeners.ts";
+export type {
+	RouteSocket,
+	WebSocketAccept,
+	WebSocketRoute,
+	WebSocketSendResult,
+} from "./core/http/websocket.ts";
 export type { Locale } from "./core/i18n/index.ts";
 export type { JudgeModel } from "./core/judging/model-judge.ts";
 export type { LogEntry, LogFn, Logger } from "./core/log.ts";
@@ -177,6 +192,7 @@ export type {
 	ServiceStartOutcome,
 	TurnEndEvent,
 	TurnEvent,
+	TurnProgressEvent,
 } from "./core/plugin.ts";
 export {
 	attachReplyFile,
@@ -205,9 +221,11 @@ export type {
 export {
 	AGENTS,
 	BACKGROUND_TURNS,
+	CONVERSATIONS,
 	DELEGATION,
 	MEMORY,
 	PRECHECKS,
+	RUNTIME,
 	SCHEDULES,
 	SKILLS,
 } from "./core/services.ts";

package/src/testing.ts

@@ -44,6 +44,7 @@ import type {
 	RoundtablePlugin,
 	TurnEndEvent,
 	TurnEvent,
+	TurnProgressEvent,
 } from "./core/plugin.ts";
 import {
 	collectContributions,
@@ -63,7 +64,13 @@ import {
 	conversationTurns,
 } from "./core/routing/conversation-turns.ts";
 import { surfacePort } from "./core/routing/surface-port.ts";
-import { AGENTS, type AgentServer, BACKGROUND_TURNS } from "./core/services.ts";
+import {
+	AGENTS,
+	type AgentServer,
+	BACKGROUND_TURNS,
+	CONVERSATIONS,
+	RUNTIME,
+} from "./core/services.ts";
 import type { ChannelKey, SessionContext } from "./core/sessions.ts";
 import { type Speaker, speakerPolicy } from "./core/speakers.ts";
 import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
@@ -99,6 +106,15 @@ export type {
 	RecordingLogger,
 } from "./core/testing/recording-logger.ts";
 export { recordingLogger } from "./core/testing/recording-logger.ts";
+export type {
+	SurfaceContractFailure,
+	SurfaceContractSubject,
+	SurfaceObservation,
+} from "./core/testing/surface-contract.ts";
+export {
+	checkSurfaceContract,
+	describeSurfaceContract,
+} from "./core/testing/surface-contract.ts";
 export type { TestHost, TestHostOptions } from "./core/testing/test-host.ts";
 export { testHost } from "./core/testing/test-host.ts";
 export type { FakeThreadHost } from "./core/testing/thread-host.ts";
@@ -177,8 +193,10 @@ export interface TestPluginOptions {
 	surfaces?: readonly ChatSurface[];
 	/**
 	 * What the plugin reads from `context.services`, one `servicePair(KEY, { ... })` per service.
-	 * `servicePair(AGENTS, { runtime })` is the runtime that `context.turns` runs turns on; without
-	 * it, a plugin that fills the `runtime` slot gets the runtime its provider builds. A service
+	 * `servicePair(RUNTIME, runtime)` is the runtime that `context.turns` runs turns on, given
+	 * whole rather than member by member; `servicePair(AGENTS, { runtime })` still works when no
+	 * `RUNTIME` is given. Without either, a plugin that fills the `runtime` slot gets the runtime its
+	 * provider builds, under both keys. A service
 	 * not given here reads as absent to `find`, and `get` names this option, except for what the
 	 * host supplies anyway: `BACKGROUND_TURNS`, the real background turns over the test's router,
 	 * and, once `AGENTS` is given, its `approvals` (the real confirmation judge over
@@ -323,6 +341,9 @@ export async function testPlugin(
 		stop: (channel) => (router ?? unlinked("conversations")).stop(channel),
 		postsInPlace: (channel) =>
 			(router ?? unlinked("conversations")).postsInPlace(channel),
+		owns: (channel) => (router ?? unlinked("conversations")).owns(channel),
+		takesBackground: (channel) =>
+			(router ?? unlinked("conversations")).takesBackground(channel),
 		...options.conversations,
 	};
 	const surfaces = surfacePort(() =>
@@ -339,6 +360,8 @@ export async function testPlugin(
 			events.push({ name: "turnEnded", turn });
 			bus.sink.turnEnded(turn);
 		},
+		// Delivered to the plugin's handlers, not recorded: a turn reports many.
+		turnProgress: (event: TurnProgressEvent) => bus.sink.turnProgress?.(event),
 		changed: () => {
 			events.push({ name: "changed" });
 			bus.sink.changed();
@@ -350,7 +373,14 @@ export async function testPlugin(
 			linked: () => {
 				if (!linked) unlinked("turns");
 			},
-			runtime: () => services.get(AGENTS).runtime,
+			runtime: () => {
+				const given = services.find(RUNTIME);
+				if (given) return given;
+				const server = services.find(AGENTS);
+				return server ? server.runtime : services.get(RUNTIME);
+			},
+			// A test that gives `CONVERSATIONS` sees each turn record its conversation.
+			registry: () => services.find(CONVERSATIONS),
 			surfaces,
 			events: sink,
 			selection: () => (linked ?? unlinked("sessions")).agentSelection(),
@@ -391,6 +421,8 @@ export async function testPlugin(
 		};
 		runtime = providers.runtime(deps);
 		// The provider's runtime serves `context.turns` unless the test gave another.
+		if (!given.has(RUNTIME.id))
+			given.set(RUNTIME.id, { key: RUNTIME, given: runtime });
 		if (!agents || !("runtime" in agents.given))
 			given.set(AGENTS.id, {
 				key: AGENTS,
@@ -411,8 +443,12 @@ export async function testPlugin(
 				}),
 			} satisfies Partial<AgentServer>,
 		});
+	// A runtime is given whole: a class's private members do not survive the partial service's proxy.
 	for (const { key, given: members } of given.values())
-		services.preset(key, partialService(key, members));
+		services.preset(
+			key,
+			key.id === RUNTIME.id ? members : partialService(key, members),
+		);
 	// The turns nobody wrote run through the same router, unless the test gave others or the plugin provides them.
 	if (
 		!given.has(BACKGROUND_TURNS.id) &&

package/templates/adapters/web/.env.example

@@ -0,0 +1,24 @@
+# Copy this file to .env and fill it in. Bun loads .env by itself; never commit it.
+
+# You: the operator who runs this host, named in the assistant's prompts.
+OWNER_NAME=
+
+# PostgreSQL. This matches docker-compose.yml: run `docker compose up -d`.
+DATABASE_URL=postgres://roundtable:roundtable@localhost:5432/roundtable
+
+# The assistant's model as <provider>/<id>, and the provider's API key (or log in with Pi and leave the key out).
+MODEL=anthropic/claude-sonnet-5-5
+# ANTHROPIC_API_KEY=
+
+# Your OpenID Connect provider: register this API there, then copy its issuer (iss), the API's
+# audience (aud), and the provider's signing keys address (jwks_uri in its discovery document).
+OIDC_ISSUER=
+OIDC_AUDIENCE=
+OIDC_JWKS_URL=
+
+# Who may chat: the role names your provider puts in the token's roles claim, comma-separated.
+CHAT_MEMBER_ROLES=
+# CHAT_ADMIN_ROLES=
+
+# The origins of the web pages that open the chat, comma-separated, such as https://chat.example.com.
+CHAT_ORIGINS=

package/templates/adapters/web/README.md

@@ -0,0 +1,15 @@
+# __PROJECT__
+
+A web chat agent server built on [pi-roundtable](https://www.npmjs.com/package/pi-roundtable) and [pi-roundtable-webchat](https://www.npmjs.com/package/pi-roundtable-webchat).
+People your OpenID Connect provider signs in chat with the assistant in private conversations; there is no Discord.
+
+1. Install: `bun install`, then copy `.env.example` to `.env` and fill it in.
+2. Check: `bunx roundtable doctor` says what is still missing and how to fix it.
+3. Run: `bunx roundtable start`, behind a reverse proxy that serves it over HTTPS.
+
+The chat is under `/chat`: a web page gets a one-time ticket from `POST /chat/tickets` with the person's token, and opens `/chat/socket` with it.
+The protocol is in `node_modules/pi-roundtable-webchat/README.md`.
+
+`roundtable.config.ts` holds the settings and lists the plugins; `plugins/` holds yours, and `persona/assistant.md` is the assistant's prompt.
+Add another plugin with `bunx roundtable add plugin <name>`, and test it with `bun test`.
+The plugin guide is in `node_modules/pi-roundtable/docs/plugins.md` and on the package's page.