pi-roundtable 0.7.19 → 0.8.0

package/src/core/config/config.ts

@@ -13,7 +13,9 @@ import {
 } from "../models.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
 import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
+import type { ChannelKey } from "../sessions.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
+import { discordShape, liftAdapters } from "./adapters.ts";
 import {
 	bool,
 	guarded,
@@ -41,33 +43,60 @@ export interface TierConfig {
 	everyone?: boolean;
 }
 
+/** The Discord bot and its guild, as the top-level `discord` or `discord()` from `pi-roundtable/discord` gives them. */
+export interface DiscordConfig {
+	/** The bot token; keep it in `.env`, not in this file. */
+	token: string;
+	/** The agent server's guild id. */
+	guild: string;
+	/** The channel the coordinator lives in. */
+	entryChannel: string;
+	/** The root slash command, without the slash; default the lowercase assistant name. */
+	rootCommand?: string;
+	/**
+	 * Whether the owner's conversations have Discord administration tools; default true. `false`
+	 * leaves the `discord-admin` addon out.
+	 */
+	admin?: boolean;
+	/**
+	 * Text appended as it is to the refusal a non-owner gets from the root command, such as a
+	 * pointer to the commands anyone may use; include the space or punctuation your language
+	 * needs before it. Default none.
+	 */
+	refusalHint?: string;
+}
+
+/** A chat network the host talks through, as its adapter's factory makes it; `adapter` names the network. */
+export interface AdapterConfig {
+	readonly adapter: string;
+}
+
+/** What `discord()` from `pi-roundtable/discord` makes: the Discord settings under the adapter's name. */
+export interface DiscordAdapterConfig extends AdapterConfig {
+	readonly adapter: "discord";
+	readonly discord: DiscordConfig;
+}
+
 /** What `roundtable.config.ts` gives `defineRoundtable`. */
 export interface RoundtableConfig {
 	/** The assistant's display name; default "Roundtable". */
 	name?: string;
 	/** The one owner: the only person who can change everything. */
 	owner: { id: string; name: string; pronouns?: Pronouns };
-	discord: {
-		/** The bot token; keep it in `.env`, not in this file. */
-		token: string;
-		/** The agent server's guild id. */
-		guild: string;
-		/** The channel the coordinator lives in. */
-		entryChannel: string;
-		/** The root slash command, without the slash; default the lowercase assistant name. */
-		rootCommand?: string;
-		/**
-		 * Whether the owner's conversations have Discord administration tools; default true. `false`
-		 * leaves the `discord-admin` addon out.
-		 */
-		admin?: boolean;
-		/**
-		 * Text appended as it is to the refusal a non-owner gets from the root command, such as a
-		 * pointer to the commands anyone may use; include the space or punctuation your language
-		 * needs before it. Default none.
-		 */
-		refusalHint?: string;
-	};
+	/**
+	 * The Discord bot, its guild, and the agent server that lives there. Leave it out for a host
+	 * without Discord: no Discord plugins, no agent server or agents, no skills, and no tool that
+	 * messages the owner on Discord; conversations come through the plugins' own surfaces. The same
+	 * settings may come as `adapters: [discord({...})]` instead, never both.
+	 */
+	discord?: DiscordConfig;
+	/**
+	 * The chat networks the host talks through, each made by its adapter's factory, such as
+	 * `discord()` from `pi-roundtable/discord`. A Discord adapter is the same as the top-level
+	 * `discord`; a chat network that comes as a plugin, such as pi-roundtable-webchat, stays in
+	 * `plugins`.
+	 */
+	adapters?: readonly AdapterConfig[];
 	database: { url: string };
 	/** Where the process keeps its files, such as pictures, attachments, and skills. */
 	dataDir: string;
@@ -89,15 +118,17 @@ export interface RoundtableConfig {
 	toolTiers?: Record<string, Tier>;
 	/** Prompt files, read once at start; `shared` starts every agent's prompt. */
 	prompts?: { shared: string; guest?: string };
-	/** The first team, created once; an agent already stored is never overwritten. */
+	/** The first team, created once; an agent already stored is never overwritten. Needs `discord`. */
 	agents?: AgentSeed[];
 	/**
-	 * Where the agents' avatars are served: the public address that reaches it, and the TCP port
-	 * (default 3000) or unix socket the process listens on. `socketMode` is the socket file's
-	 * permission bits (default `0o660`); widen it only for a proxy that runs as another user.
+	 * The `public` listener: the public address that reaches it, and the TCP port (default 3000) or
+	 * unix socket the process listens on. `socketMode` is the socket file's permission bits
+	 * (default `0o660`); widen it only for a proxy that runs as another user. With `discord` it is
+	 * required, with `publicUrl`, the address the agents' avatars are served from; without
+	 * `discord` leave it out when no plugin serves HTTP, and the host opens no listener.
 	 */
-	http: {
-		publicUrl: string;
+	http?: {
+		publicUrl?: string;
 		port?: number;
 		hostname?: string;
 		socketPath?: string;
@@ -109,13 +140,14 @@ export interface RoundtableConfig {
 	workDir?: string;
 	/**
 	 * The agents' scratch dir: their shell runs with TMPDIR pointing to it, and writes and removals
-	 * inside it run without a hold. Default `<os temp dir>/<discord.rootCommand>-scratch`.
+	 * inside it run without a hold. Default `<os temp dir>/<slug>-scratch`, where the slug is
+	 * `discord.rootCommand`, or the lowercase assistant name without Discord.
 	 */
 	scratchDir?: string;
 	/**
 	 * Where the skill registry reads built-in skills and keeps linked repositories. `false` leaves
 	 * the `skills` addon out: agents carry no skills, and no skill tools exist. Stored skills stay
-	 * in their tables.
+	 * in their tables. Without `discord` there are no agents, so the addon is off.
 	 */
 	skills?: false | { builtinDir?: string; reposDir?: string };
 	/**
@@ -123,8 +155,13 @@ export interface RoundtableConfig {
 	 * `memory` addon out: no memory tools, no memory prompt block, and the table stays as it is.
 	 */
 	memory?: boolean;
-	/** The agent that investigates the process's own errors, by name. */
-	ops?: { agent: string };
+	/**
+	 * Where the process's own errors are reported: to an agent, by name, in its channel (needs
+	 * `discord`), or to a conversation, by its key `<surface>:<id>`, as a visible message and a
+	 * report turn its claim answers. The host does not start when no chat surface serves the
+	 * conversation or no plugin's claim owns it; the web chat takes no error reports.
+	 */
+	ops?: { agent: string } | { conversation: string };
 	/**
 	 * Whether a turn posts the text it writes before its final answer as it goes: long or
 	 * structured text as ordinary messages, short narration and the tools called in one small
@@ -155,14 +192,7 @@ const schema = shape({
 		name: text,
 		pronouns: optional(oneOf<Pronouns>("he", "she", "they")),
 	}),
-	discord: shape({
-		token: text,
-		guild: text,
-		entryChannel: text,
-		rootCommand: optional(text),
-		admin: optional(bool),
-		refusalHint: optional(text),
-	}),
+	discord: optional(discordShape),
 	database: shape({ url: text }),
 	dataDir: text,
 	agentDir: optional(text),
@@ -199,13 +229,15 @@ const schema = shape({
 			}),
 		),
 	),
-	http: shape({
-		publicUrl: text,
-		port: optional(integer(1, 65535)),
-		hostname: optional(text),
-		socketPath: optional(text),
-		socketMode: optional(integer(0, 0o777)),
-	}),
+	http: optional(
+		shape({
+			publicUrl: optional(text),
+			port: optional(integer(1, 65535)),
+			hostname: optional(text),
+			socketPath: optional(text),
+			socketMode: optional(integer(0, 0o777)),
+		}),
+	),
 	avatar: optional(text),
 	workDir: optional(text),
 	scratchDir: optional(text),
@@ -213,7 +245,7 @@ const schema = shape({
 		orOff(shape({ builtinDir: optional(text), reposDir: optional(text) })),
 	),
 	memory: optional(bool),
-	ops: optional(shape({ agent: text })),
+	ops: optional(shape({ agent: optional(text), conversation: optional(text) })),
 	interimText: optional(oneOf<InterimTextMode>("on", "off")),
 	interimPrimaryChars: optional(integer(1, 100_000)),
 	plugins: optional(
@@ -232,8 +264,14 @@ const PRONOUNS: Record<Pronouns, OwnerIdentity["pronouns"]> = {
 /** The configuration with every default filled in. */
 export interface ResolvedConfig {
 	name: string;
+	/**
+	 * The process's short name: the logger's and the scratch dir's, and the root slash command's
+	 * with Discord. `discord.rootCommand` when Discord is on, else the lowercase assistant name.
+	 */
+	slug: string;
 	owner: OwnerIdentity & { id: string };
-	discord: {
+	/** Undefined on a host without Discord. */
+	discord?: {
 		token: string;
 		guild: string;
 		entryChannel: string;
@@ -254,8 +292,10 @@ export interface ResolvedConfig {
 	toolTiers: Record<string, Tier>;
 	prompts: { shared?: string; guest?: string };
 	agents: AgentSeed[];
-	http: {
-		publicUrl: string;
+	/** Undefined when no `http` is configured, and the host opens no `public` listener. */
+	http?: {
+		/** Always set with Discord. */
+		publicUrl?: string;
 		port: number;
 		hostname?: string;
 		socketPath?: string;
@@ -267,7 +307,7 @@ export interface ResolvedConfig {
 	/** `false` when the skills addon is off. */
 	skills: false | { builtinDir?: string; reposDir?: string };
 	memory: boolean;
-	ops?: { agent: string };
+	ops?: { agent: string } | { conversation: ChannelKey };
 	interimText: InterimTextMode;
 	interimPrimaryChars: number;
 	plugins: RoundtablePlugin[];
@@ -282,32 +322,84 @@ function modelOf(value: string, path: string): ModelRef {
 	return parsed;
 }
 
+/** Where the errors go: one of an agent or a conversation; an agent only where the agents live. */
+function opsOf(
+	ops: { agent?: string; conversation?: string } | undefined,
+	withDiscord: boolean,
+): ResolvedConfig["ops"] {
+	if (!ops) return undefined;
+	const { agent, conversation } = ops;
+	if (agent !== undefined && conversation !== undefined)
+		throw new ConfigError(
+			"config ops: name an agent or a conversation, not both. Keep the one the reports go to.",
+		);
+	if (agent !== undefined) {
+		if (!withDiscord)
+			throw new ConfigError(
+				'config ops.agent: the agents live in Discord, which is not configured. Report to a conversation a plugin\'s chat surface serves instead, with ops: { conversation: "<surface>:<id>" }; the web chat takes no error reports.',
+			);
+		return { agent };
+	}
+	if (conversation === undefined)
+		throw new ConfigError(
+			'config ops: name an agent or a conversation, such as ops: { agent: "infra" } or ops: { conversation: "<surface>:<id>" }.',
+		);
+	if (!/^[^:]+:.+$/.test(conversation))
+		throw new ConfigError(
+			`config ops.conversation: expected a conversation key <surface>:<id>, got ${JSON.stringify(conversation)}. Write the surface's prefix, a colon, and the conversation's id.`,
+		);
+	return { conversation: conversation as ChannelKey };
+}
+
+/** Refuses what only the agent server serves on a host without Discord, naming the key. */
+function refuseAgentServerKeys(config: RoundtableConfig): void {
+	if (config.agents && config.agents.length > 0)
+		throw new ConfigError(
+			"config agents: the agents live in Discord, which is not configured. Configure discord, or remove agents.",
+		);
+	if (config.skills)
+		throw new ConfigError(
+			"config skills: the skills are the agents', and the agents live in Discord, which is not configured. Configure discord, or remove skills.",
+		);
+}
+
 /** The configuration checked against its schema, defaults filled; throws a ConfigError naming the key and the fix. */
 export function resolveConfig(input: unknown): ResolvedConfig {
-	const config = schema.check(input, "") as RoundtableConfig;
+	const config = schema.check(liftAdapters(input), "") as RoundtableConfig;
 	const name = config.name ?? "Roundtable";
 	const model = modelOf(config.model, "model");
 	const thinking = config.thinking ?? "medium";
-	const rootCommand =
-		config.discord.rootCommand ??
-		name.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+	const { discord, http } = config;
+	if (discord && !http?.publicUrl)
+		throw new ConfigError(
+			"config http.publicUrl: required with discord, expected the public address that reaches the bot; Discord fetches the agents' avatars from it. Add it to roundtable.config.ts.",
+		);
+	if (!discord) refuseAgentServerKeys(config);
+	const slug =
+		discord?.rootCommand ?? name.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+	const ops = opsOf(config.ops, discord !== undefined);
 	return {
 		name,
+		slug,
 		owner: {
 			id: config.owner.id,
 			name: config.owner.name,
 			pronouns: PRONOUNS[config.owner.pronouns ?? "they"],
 		},
-		discord: {
-			token: config.discord.token,
-			guild: config.discord.guild,
-			entryChannel: config.discord.entryChannel,
-			rootCommand,
-			admin: config.discord.admin ?? true,
-			...(config.discord.refusalHint === undefined
-				? {}
-				: { refusalHint: config.discord.refusalHint }),
-		},
+		...(discord
+			? {
+					discord: {
+						token: discord.token,
+						guild: discord.guild,
+						entryChannel: discord.entryChannel,
+						rootCommand: slug,
+						admin: discord.admin ?? true,
+						...(discord.refusalHint === undefined
+							? {}
+							: { refusalHint: discord.refusalHint }),
+					},
+				}
+			: {}),
 		databaseUrl: config.database.url,
 		dataDir: config.dataDir,
 		agentDir: config.agentDir ?? `${config.dataDir}/pi`,
@@ -334,21 +426,26 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 		toolTiers: config.toolTiers ?? {},
 		prompts: config.prompts ?? {},
 		agents: config.agents ?? [],
-		http: {
-			publicUrl: config.http.publicUrl,
-			port: config.http.port ?? 3000,
-			...(config.http.hostname ? { hostname: config.http.hostname } : {}),
-			...(config.http.socketPath ? { socketPath: config.http.socketPath } : {}),
-			...(config.http.socketMode === undefined
-				? {}
-				: { socketMode: config.http.socketMode }),
-		},
+		...(http
+			? {
+					http: {
+						...(http.publicUrl ? { publicUrl: http.publicUrl } : {}),
+						port: http.port ?? 3000,
+						...(http.hostname ? { hostname: http.hostname } : {}),
+						...(http.socketPath ? { socketPath: http.socketPath } : {}),
+						...(http.socketMode === undefined
+							? {}
+							: { socketMode: http.socketMode }),
+					},
+				}
+			: {}),
 		...(config.avatar ? { avatar: config.avatar } : {}),
 		workDir: config.workDir ?? `${config.dataDir}/work`,
-		scratchDir: config.scratchDir ?? join(tmpdir(), `${rootCommand}-scratch`),
-		skills: config.skills ?? {},
+		scratchDir: config.scratchDir ?? join(tmpdir(), `${slug}-scratch`),
+		// Without Discord there are no agents to carry skills, so the addon is off.
+		skills: config.skills ?? (discord ? {} : false),
 		memory: config.memory ?? true,
-		...(config.ops ? { ops: config.ops } : {}),
+		...(ops ? { ops } : {}),
 		interimText: config.interimText ?? "on",
 		interimPrimaryChars: config.interimPrimaryChars ?? PRIMARY_CHARS,
 		plugins: config.plugins ?? [],

package/src/core/contract/channels.ts

@@ -178,6 +178,10 @@ export interface ConversationPort {
 	stop(channel: ChannelKey): boolean;
 	/** Whether reports of work started in the channel stay in it, by its owner's policy. */
 	postsInPlace(channel: ChannelKey): boolean;
+	/** Whether a claim owns the channel, so its messages and background turns reach a conversation. */
+	owns(channel: ChannelKey): boolean;
+	/** Whether the claim that owns the channel runs background turns there; false when none owns it. */
+	takesBackground(channel: ChannelKey): boolean;
 }
 
 /** The host's channel queue, as plugins use it. */

package/src/core/contract/providers.ts

@@ -68,8 +68,9 @@ export interface Providers {
 	images: ImageDrawer;
 	/**
 	 * Builds the runtime that runs the agent server's conversations and every turn run through
-	 * `context.turns`, in place of the Pi runtime. The default refuses: the agent server builds the
-	 * Pi runtime itself when no plugin fills this slot, so check `filled` before calling it.
+	 * `context.turns`, in place of the Pi runtime. The default refuses: the host's runtime plugin
+	 * builds the Pi runtime itself when no plugin fills this slot. Read the running runtime from
+	 * `services.get(RUNTIME)` rather than calling this.
 	 */
 	runtime: RuntimeFactory;
 }

package/src/core/contract/runtime.ts

@@ -109,7 +109,7 @@ export interface HeldActionStore {
 	): Promise<void>;
 }
 
-/** What the agent server hands a runtime provider when it builds the runtime. */
+/** What the host's runtime plugin hands a runtime provider when it builds the runtime. */
 export interface RuntimeDeps {
 	logger: Logger;
 	/** The host's locale and time zone. */
@@ -131,13 +131,17 @@ export interface RuntimeDeps {
 		conversation: ChannelKey,
 		speaker?: Speaker,
 	): OwnerPrompts | undefined;
-	/** The agent server's per-agent settings, for agent turns. */
-	agents: AgentSessions;
+	/**
+	 * The agent server's per-agent settings, for agent turns. The runtime is built before the agent
+	 * server, so read this when a turn runs, not in the factory; it stays undefined on a host without
+	 * the agent server, where no agent turn runs.
+	 */
+	readonly agents?: AgentSessions;
 	/** Where held actions persist across restarts. */
 	confirmations: HeldActionStore;
 	/** The host's judge, resolved from the `judge` slot. */
 	judge: Judge;
 }
 
-/** Builds the runtime, once, when the agent server sets up. */
+/** Builds the runtime, once, when the host's runtime plugin sets up. */
 export type RuntimeFactory = (deps: RuntimeDeps) => AgentRuntime;

package/src/core/contract/surface.ts

@@ -1,6 +1,7 @@
 import type { OutboundReply } from "../domain/conversation.ts";
 import type { InterimPosts } from "../domain/interim.ts";
 import type { OwnerPrompts } from "../domain/owner-prompts.ts";
+import type { TurnProgress } from "../domain/progress.ts";
 import { PluginError } from "../errors.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
@@ -74,6 +75,12 @@ export interface ChatSurface {
 	 * may edit in place. Absent, or undefined, = only the final reply is posted.
 	 */
 	interim?(channel: ChannelKey): InterimPosts | undefined;
+	/**
+	 * Shows what a running turn writes and which tools it runs, as it goes, such as a live preview
+	 * in a web chat. Called between the turn's start and its reply; a rejection is logged and the
+	 * turn goes on. Absent = the surface shows only the final reply.
+	 */
+	progress?(channel: ChannelKey, event: TurnProgress): Promise<void> | void;
 }
 
 /**
@@ -95,4 +102,10 @@ export interface SurfacePort {
 	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
 	/** The channel's interim posts; undefined when its surface has none. */
 	interim(channel: ChannelKey): InterimPosts | undefined;
+	/**
+	 * Shows a running turn's progress; a no-op when no surface serves the channel or its surface
+	 * shows none. The host's port always has it; it is optional so a port written before 0.8 still
+	 * type-checks, and a turn run over one without it shows no progress.
+	 */
+	progress?(channel: ChannelKey, event: TurnProgress): Promise<void>;
 }

package/src/core/conversations/conversation-registry.ts

@@ -0,0 +1,42 @@
+import type { ChannelKey } from "../sessions.ts";
+
+/** Who may take part: `private` belongs to one principal, `shared` to whoever its claim admits. */
+export type ConversationVisibility = "private" | "shared";
+
+/** What the first turn of a conversation records about it. */
+export interface ConversationRegistration {
+	key: ChannelKey;
+	/** The conversation's kind, such as "study"; the persona its session runs. */
+	kind: string;
+	visibility: ConversationVisibility;
+	/** Whose conversation it is: the speaker's id, for a private one. */
+	principalId?: string;
+	/** A name to list it by. */
+	title?: string;
+}
+
+/** A conversation the host knows: who it belongs to and when it was last active. */
+export interface ConversationRecord extends ConversationRegistration {
+	/** The prefix of its key, such as "web". */
+	surface: string;
+	createdAt: Date;
+	lastActiveAt: Date;
+}
+
+/**
+ * The conversations run through `context.turns`, recorded at their first turn. Its kind,
+ * visibility, and principal are fixed then; each later turn only marks it active. Who may speak
+ * in it stays the claim's decision: the registry records, it does not refuse.
+ */
+export interface ConversationRegistry {
+	/** Records the conversation at its first turn, or marks a known one active; returns what is stored. */
+	register(entry: ConversationRegistration): Promise<ConversationRecord>;
+	get(key: ChannelKey): Promise<ConversationRecord | undefined>;
+	/** One principal's conversations, or every one; the most recently active first. */
+	list(filter?: { principal?: string }): Promise<ConversationRecord[]>;
+	/** Names a conversation, or clears its name; undefined when the key is unknown. */
+	setTitle(
+		key: ChannelKey,
+		title: string | undefined,
+	): Promise<ConversationRecord | undefined>;
+}

package/src/core/conversations/conversation-store.ts

@@ -0,0 +1,113 @@
+import type { SQL } from "bun";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { Migration } from "../db/migrations.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type {
+	ConversationRecord,
+	ConversationRegistration,
+	ConversationRegistry,
+	ConversationVisibility,
+} from "./conversation-registry.ts";
+
+interface Row {
+	key: string;
+	surface: string;
+	kind: string;
+	principal_id: string | null;
+	visibility: ConversationVisibility;
+	title: string | null;
+	created_at: Date;
+	last_active_at: Date;
+}
+
+function recordOf(row: Row): ConversationRecord {
+	return {
+		key: row.key as ChannelKey,
+		surface: row.surface,
+		kind: row.kind,
+		visibility: row.visibility,
+		...(row.principal_id === null ? {} : { principalId: row.principal_id }),
+		...(row.title === null ? {} : { title: row.title }),
+		createdAt: row.created_at,
+		lastActiveAt: row.last_active_at,
+	};
+}
+
+/** The conversation registry in the `conversations` table. */
+export class PgConversationRegistry implements ConversationRegistry {
+	readonly #sql: SQL;
+
+	private constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	/** The registry's table; the host runs this before the registry attaches. */
+	static readonly migration: Migration = {
+		name: "conversations",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS conversations (
+					key text PRIMARY KEY,
+					surface text NOT NULL,
+					kind text NOT NULL,
+					principal_id text,
+					visibility text NOT NULL CHECK (visibility IN ('private', 'shared')),
+					title text,
+					created_at timestamptz NOT NULL DEFAULT now(),
+					last_active_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`
+				CREATE INDEX IF NOT EXISTS conversations_principal
+				ON conversations (principal_id, last_active_at DESC)`;
+		},
+	};
+
+	/** The registry over the host's migrated pool. */
+	static async attach(sql: SQL): Promise<PgConversationRegistry> {
+		return new PgConversationRegistry(sql);
+	}
+
+	async register(entry: ConversationRegistration): Promise<ConversationRecord> {
+		const { surface } = parseChannelKey(entry.key);
+		const rows: Row[] = await this.#sql`
+			INSERT INTO conversations (key, surface, kind, principal_id, visibility, title)
+			VALUES (${entry.key}, ${surface}, ${entry.kind}, ${entry.principalId ?? null},
+				${entry.visibility}, ${entry.title ?? null})
+			ON CONFLICT (key) DO UPDATE SET last_active_at = now()
+			RETURNING *`;
+		const [row] = rows;
+		if (!row) throw new Error(`conversation ${entry.key} was not recorded`);
+		return recordOf(row);
+	}
+
+	async get(key: ChannelKey): Promise<ConversationRecord | undefined> {
+		const rows: Row[] = await this.#sql`
+			SELECT * FROM conversations WHERE key = ${key}`;
+		const [row] = rows;
+		return row ? recordOf(row) : undefined;
+	}
+
+	async list(
+		filter: { principal?: string } = {},
+	): Promise<ConversationRecord[]> {
+		const rows: Row[] =
+			filter.principal === undefined
+				? await this.#sql`
+					SELECT * FROM conversations ORDER BY last_active_at DESC, key`
+				: await this.#sql`
+					SELECT * FROM conversations WHERE principal_id = ${filter.principal}
+					ORDER BY last_active_at DESC, key`;
+		return rows.map(recordOf);
+	}
+
+	async setTitle(
+		key: ChannelKey,
+		title: string | undefined,
+	): Promise<ConversationRecord | undefined> {
+		const rows: Row[] = await this.#sql`
+			UPDATE conversations SET title = ${title ?? null} WHERE key = ${key}
+			RETURNING *`;
+		const [row] = rows;
+		return row ? recordOf(row) : undefined;
+	}
+}

package/src/core/conversations/conversations-plugin.ts

@@ -0,0 +1,29 @@
+import type { SQL } from "bun";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { CONVERSATIONS } from "../services.ts";
+import type { ConversationRegistry } from "./conversation-registry.ts";
+import { PgConversationRegistry } from "./conversation-store.ts";
+
+/** The name of the conversation registry's plugin, as the migration ledger names it. */
+export const CONVERSATIONS_PLUGIN = "conversations";
+
+/**
+ * The conversation registry, provided as `CONVERSATIONS`: every conversation run through
+ * `context.turns`, recorded at its first turn. No session file moves; a conversation from before
+ * the registry is recorded at its next turn.
+ */
+export function conversationsPlugin(
+	/** Opens the registry; a test hands a stand-in, so the plugin sets up without a database. */
+	open: (sql: SQL) => Promise<ConversationRegistry> = (sql) =>
+		PgConversationRegistry.attach(sql),
+): RoundtablePlugin {
+	return {
+		name: CONVERSATIONS_PLUGIN,
+		migrations: [PgConversationRegistry.migration],
+		provides: [CONVERSATIONS],
+		setup: async ({ database, services }) => {
+			services.provide(CONVERSATIONS, await open(database()));
+			return {};
+		},
+	};
+}