pi-roundtable 0.7.19 → 0.9.0

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,22 @@
+# __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`.
+Core `access` in `roundtable.config.ts` decides admission; token roles are prefixed with `web:role:` there.
+New admitted users get principals, and linked Discord/web identities share private memory and quotas.
+Link identities with `bunx roundtable principal link <principal> <identity>`; use `principal list` to inspect them.
+
+The private inbox is `GET /chat/notices`, with `POST /chat/notices/<id>/read` to acknowledge an entry.
+Online connections also receive additive `notice` frames.
+Schedules and delegated reports can answer in their creator's private conversation; enable their tools in the persona selection only where intended and allowed by tier.
+
+`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.

package/templates/adapters/web/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+	"name": "__PROJECT__",
+	"private": true,
+	"type": "module",
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"scripts": {
+		"doctor": "roundtable doctor",
+		"start": "roundtable start",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"pi-roundtable": "__VERSION__",
+		"pi-roundtable-webchat": "__VERSION__",
+		"pi-self-compact": "0.2.0",
+		"typebox": "1.3.34"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@types/bun": "1.4.2",
+		"typescript": "7.0.2"
+	}
+}

package/templates/adapters/web/persona/assistant.md

@@ -0,0 +1,2 @@
+You are an assistant people reach through a web chat. Each conversation belongs to the one person who opened it.
+Be helpful, be honest about what you do not know, and keep replies short unless asked for detail.

package/templates/adapters/web/roundtable.config.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import type { RoundtableConfig } from "pi-roundtable";
+import { oidcJwtVerifier, webChat } from "pi-roundtable-webchat";
+import { hello } from "./plugins/hello.ts";
+import { selfCompact } from "./plugins/self-compact.ts";
+
+// Credentials and ids come from .env, which Bun loads on its own; nothing secret belongs in this file.
+const env = (name: string): string => process.env[name] ?? "";
+const list = (name: string): string[] =>
+	env(name)
+		.split(",")
+		.map((value) => value.trim())
+		.filter(Boolean);
+
+export default {
+	name: "Roundtable",
+	// The operator who runs this host, as the host's owner. People sign in through your OpenID
+	// Connect provider instead; core access maps their verified, surface-prefixed roles to tiers.
+	access: {
+		owners: [{ name: env("OWNER_NAME"), principal: "operator" }],
+		members: {
+			roles: list("CHAT_MEMBER_ROLES").map((role) => `web:role:${role}`),
+		},
+		admins: {
+			roles: list("CHAT_ADMIN_ROLES").map((role) => `web:role:${role}`),
+		},
+	},
+	database: { url: env("DATABASE_URL") },
+	// Paths are relative to the project directory, where the roundtable command runs.
+	dataDir: "./data",
+	model: env("MODEL"),
+	// Serve behind a reverse proxy that terminates TLS; the web chat lives under /chat.
+	http: { port: 3000, hostname: "127.0.0.1" },
+	plugins: [
+		selfCompact,
+		hello,
+		webChat({
+			// Accepts only a person's access token. Pin your tenant and pick a stable subject claim
+			// with subjectClaim and check: see "Provider settings" in the pi-roundtable-webchat README.
+			verifier: oidcJwtVerifier({
+				jwksUrl: env("OIDC_JWKS_URL"),
+				issuers: [env("OIDC_ISSUER")],
+				audiences: [env("OIDC_AUDIENCE")],
+			}),
+			origins: list("CHAT_ORIGINS"),
+			personas: [
+				{
+					kind: "assistant",
+					label: "Assistant",
+					prompt: () => readFileSync("./persona/assistant.md", "utf8"),
+					// The tools of its turns, by name. Schedules, delegated reports and notify can reach
+					// this private conversation; add those tools only where intended and permitted by tier.
+					// Leave out web_search and fetch_content unless people may make the server fetch any address.
+					selection: { tools: ["hello_greet"], groups: [] },
+				},
+			],
+		}),
+	],
+} satisfies RoundtableConfig;

package/templates/package.json.tmpl

@@ -14,6 +14,7 @@
 	},
 	"dependencies": {
 		"pi-roundtable": "__VERSION__",
+		"pi-self-compact": "0.2.0",
 		"typebox": "1.3.34"
 	},
 	"devDependencies": {

package/templates/plugins/self-compact.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from "pi-roundtable";
+
+/**
+ * Loads the Pi package pi-self-compact in every conversation session. Its compact_session tool
+ * lets a turn compact a long conversation; every session carries it, so startup stops with
+ * "required tools are not registered: compact_session" when no plugin loads it.
+ */
+export const selfCompact = definePlugin({
+	name: "self-compact",
+	setup: () => ({ piPackages: ["pi-self-compact"] }),
+});

package/templates/roundtable.config.ts

@@ -1,13 +1,25 @@
 import type { RoundtableConfig } from "pi-roundtable";
 import { agents } from "./agents.ts";
 import { hello } from "./plugins/hello.ts";
+import { selfCompact } from "./plugins/self-compact.ts";
 
 // Credentials and ids come from .env, which Bun loads on its own; nothing secret belongs in this file.
 const env = (name: string): string => process.env[name] ?? "";
 
 export default {
 	name: "Roundtable",
-	owner: { id: env("OWNER_ID"), name: env("OWNER_NAME") },
+	// Who the host serves. You are the owner: your principal and your Discord identity are your
+	// Discord user id. Add admins and members by Discord user or role, such as
+	// members: { roles: ["discord:role:<role id>"] }.
+	access: {
+		owners: [
+			{
+				name: env("OWNER_NAME"),
+				principal: env("OWNER_ID"),
+				identities: [`discord:${env("OWNER_ID")}`],
+			},
+		],
+	},
 	discord: {
 		token: env("DISCORD_TOKEN"),
 		guild: env("DISCORD_GUILD_ID"),
@@ -20,5 +32,5 @@ export default {
 	http: { publicUrl: env("PUBLIC_URL") },
 	prompts: { shared: "./persona/shared.md" },
 	agents,
-	plugins: [hello],
+	plugins: [selfCompact, hello],
 } satisfies RoundtableConfig;

package/src/core/domain/owner-prompts.ts

@@ -1,45 +0,0 @@
-import type { Tier } from "../speakers.ts";
-/**
- * The owner answering inside a running turn: a card in the turn's channel that only they may
- * answer. Unanswered cards expire; a stopped turn cancels its open cards.
- */
-export type Approval = "approved" | "declined" | "expired" | "cancelled";
-
-export interface AskOption {
-	label: string;
-	description?: string;
-}
-
-export interface OwnerQuestion {
-	question: string;
-	/** Up to 25; none means a free-text answer. */
-	options: readonly AskOption[];
-	/** More than one option may be chosen. */
-	multi: boolean;
-	/** They may write an answer of their own besides the options. */
-	allowOther: boolean;
-}
-
-export interface OwnerAnswer {
-	/** The chosen options' labels, in the order they were offered. */
-	choices: string[];
-	/** What they wrote himself, if anything. */
-	text?: string;
-}
-
-export interface OwnerPrompts {
-	/** Asks them to approve an action; `signal` cancels the card when the turn stops. */
-	confirm(
-		title: string,
-		message: string,
-		signal?: AbortSignal,
-		/** The lowest tier that may approve; the owner only when absent. */
-		minTier?: Tier,
-	): Promise<Approval>;
-	/** Asks them a question; undefined when it expired or was cancelled. */
-	ask(
-		title: string,
-		question: OwnerQuestion,
-		signal?: AbortSignal,
-	): Promise<OwnerAnswer | undefined>;
-}