pi-roundtable 0.1.0

package/src/core/config/schema.ts

@@ -0,0 +1,181 @@
+import { ConfigError } from "../domain/errors.ts";
+import { nearest } from "../registry/contributions.ts";
+
+/**
+ * One field of a configuration: how to check a value and what to say when it is wrong. A
+ * checker returns the value it accepts, so a field may also normalize.
+ */
+export interface Field<T> {
+	/** What the field holds, for the message: `a string`, `one of a, b`. */
+	describe: string;
+	check(value: unknown, path: string): T;
+}
+
+const wrong = (path: string, wanted: string, got: unknown): ConfigError =>
+	new ConfigError(
+		`config ${path}: expected ${wanted}, got ${
+			got === undefined ? "nothing" : JSON.stringify(got)
+		}. Fix the value in roundtable.config.ts.`,
+	);
+
+/** A non-empty string. */
+export const text: Field<string> = {
+	describe: "a non-empty string",
+	check: (value, path) => {
+		if (typeof value !== "string" || value.trim() === "")
+			throw wrong(path, "a non-empty string", value);
+		return value;
+	},
+};
+
+/** True or false. */
+export const bool: Field<boolean> = {
+	describe: "true or false",
+	check: (value, path) => {
+		if (typeof value !== "boolean") throw wrong(path, "true or false", value);
+		return value;
+	},
+};
+
+/** An integer from `min` to `max`. */
+export const integer = (min: number, max: number): Field<number> => ({
+	describe: `an integer from ${min} to ${max}`,
+	check: (value, path) => {
+		if (
+			!Number.isInteger(value) ||
+			(value as number) < min ||
+			(value as number) > max
+		)
+			throw wrong(path, `an integer from ${min} to ${max}`, value);
+		return value as number;
+	},
+});
+
+/** A number from `min` to `max`. */
+export const number = (min: number, max: number): Field<number> => ({
+	describe: `a number from ${min} to ${max}`,
+	check: (value, path) => {
+		if (
+			typeof value !== "number" ||
+			Number.isNaN(value) ||
+			value < min ||
+			value > max
+		)
+			throw wrong(path, `a number from ${min} to ${max}`, value);
+		return value;
+	},
+});
+
+/** One of the listed strings. */
+export const oneOf = <T extends string>(
+	...allowed: readonly T[]
+): Field<T> => ({
+	describe: `one of ${allowed.join(", ")}`,
+	check: (value, path) => {
+		if (typeof value !== "string" || !allowed.includes(value as T))
+			throw wrong(path, `one of ${allowed.join(", ")}`, value);
+		return value as T;
+	},
+});
+
+/** A list whose items each pass `item`. */
+export const list = <T>(item: Field<T>): Field<T[]> => ({
+	describe: `a list of ${item.describe}`,
+	check: (value, path) => {
+		if (!Array.isArray(value))
+			throw wrong(path, `a list of ${item.describe}`, value);
+		return value.map((entry, index) => item.check(entry, `${path}[${index}]`));
+	},
+});
+
+/** An object whose every value passes `item`, keyed by any string. */
+export const record = <T>(item: Field<T>): Field<Record<string, T>> => ({
+	describe: `an object of ${item.describe}`,
+	check: (value, path) => {
+		if (typeof value !== "object" || value === null || Array.isArray(value))
+			throw wrong(path, `an object of ${item.describe}`, value);
+		return Object.fromEntries(
+			Object.entries(value).map(([key, entry]) => [
+				key,
+				item.check(entry, `${path}.${key}`),
+			]),
+		);
+	},
+});
+
+/** A value a caller-supplied predicate accepts, such as a plugin object. */
+export const guarded = <T>(
+	describe: string,
+	accepts: (value: unknown) => value is T,
+): Field<T> => ({
+	describe,
+	check: (value, path) => {
+		if (!accepts(value)) throw wrong(path, describe, value);
+		return value;
+	},
+});
+
+/** A field that may be left out. */
+export type Optional<T> = { optional: Field<T> };
+
+export const optional = <T>(field: Field<T>): Optional<T> => ({
+	optional: field,
+});
+
+type Shape = Record<string, Field<unknown> | Optional<unknown>>;
+
+type Checked<S extends Shape> = {
+	[K in keyof S as S[K] extends Optional<unknown>
+		? never
+		: K]: S[K] extends Field<infer T> ? T : never;
+} & {
+	[K in keyof S as S[K] extends Optional<unknown>
+		? K
+		: never]?: S[K] extends Optional<infer T> ? T : never;
+};
+
+const isOptional = (
+	field: Field<unknown> | Optional<unknown>,
+): field is Optional<unknown> => "optional" in field;
+
+/**
+ * An object with the named fields. A key the shape does not name is an error that names the
+ * nearest key that is; a missing required key names the key.
+ */
+export function shape<S extends Shape>(fields: S): Field<Checked<S>> {
+	const keys = Object.keys(fields);
+	return {
+		describe: `an object with ${keys.join(", ")}`,
+		check: (value, path) => {
+			if (typeof value !== "object" || value === null || Array.isArray(value))
+				throw wrong(path, "an object", value);
+			const given = value as Record<string, unknown>;
+			for (const key of Object.keys(given)) {
+				if (keys.includes(key)) continue;
+				const meant = nearest(key, keys);
+				throw new ConfigError(
+					`config ${path === "" ? key : `${path}.${key}`}: unknown key.${
+						meant ? ` Did you mean "${meant}"?` : ""
+					} The keys here are ${keys.join(", ")}.`,
+				);
+			}
+			const out: Record<string, unknown> = {};
+			for (const key of keys) {
+				const field = fields[key];
+				if (!field) continue;
+				const at = path === "" ? key : `${path}.${key}`;
+				const raw = given[key];
+				if (isOptional(field)) {
+					if (raw !== undefined) out[key] = field.optional.check(raw, at);
+					continue;
+				}
+				if (raw === undefined)
+					throw new ConfigError(
+						`config ${at}: required, expected ${field.describe}. Add it to roundtable.config.ts.`,
+					);
+				out[key] = field.check(raw, at);
+			}
+			return out as Checked<S>;
+		},
+	};
+}

package/src/core/contract/channels.ts

@@ -0,0 +1,152 @@
+import type { ChannelKey } from "../sessions.ts";
+import type { Tier } from "../speakers.ts";
+
+/** A file attached to a chat message, as the surface reports it; nothing is downloaded yet. */
+export interface AttachmentRef {
+	url: string;
+	name: string;
+	/** MIME type when the surface knows it. */
+	contentType?: string;
+	size: number;
+}
+
+/** The facts a surface reports about one incoming message; it never decides who may talk. */
+export interface InboundMessage {
+	channel: ChannelKey;
+	/** Unique per surface; keeps the files of different messages apart. */
+	messageId: string;
+	authorId: string;
+	/** How the author appears in the channel, for example a server nickname. */
+	authorName: string;
+	authorIsBot: boolean;
+	/** The roles the author holds in the message's server; absent in direct messages. */
+	authorRoleIds?: readonly string[];
+	/** The webhook that posted the message; its name is `authorName`. */
+	webhookId?: string;
+	/** The webhook is one the assistant posts through itself, such as an agent's voice. */
+	ownWebhook?: boolean;
+	isDirect: boolean;
+	/** The server the message was posted in; absent in direct messages. */
+	guildId?: string;
+	mentionsBot: boolean;
+	/** The message replies to one of the bot's messages. */
+	repliesToBot: boolean;
+	/** Message text with the bot mention removed. */
+	text: string;
+	attachments: AttachmentRef[];
+	/** The message this one replies to, as far as the surface can read it. */
+	reference?: {
+		text: string;
+		attachments: AttachmentRef[];
+		/** The name a webhook posted the referenced message under, such as an agent's. */
+		webhookName?: string;
+	};
+	/** The message the author forwarded with this one; its attachments are in `attachments`. */
+	forwarded?: {
+		text: string;
+		/** The source channel, as `<#id>`, and a link to the original message. */
+		channelMention: string;
+		url: string;
+	};
+}
+
+/** Reactions on a message sent during a turn: added to that turn, or waiting for its own. */
+export const STEERED_MARK = "↪️";
+export const QUEUED_MARK = "⏳";
+
+/** How a turn nobody wrote in the channel ended. */
+export type ScheduledOutcome =
+	| { status: "ran" }
+	| { status: "failed"; error: string }
+	| { status: "skipped"; reason: string };
+
+/** A turn nobody wrote in the channel: a schedule's, or a report of work done elsewhere. */
+export interface BackgroundTurn {
+	channel: ChannelKey;
+	/** Whose turn a schedule asked for; a claim skips a mode it does not serve. */
+	mode: "owner" | "party";
+	author: { id: string; name: string };
+	/**
+	 * The tier the turn runs at, which is its creator's when a person set it up; absent for
+	 * the operator's own automation, which runs at the owner's.
+	 */
+	tier?: Tier;
+	turnId: string;
+	text: string;
+	/** It delivers a report the owner is waiting for, so it may ask him on cards. */
+	report?: boolean;
+}
+
+/** What a claim does with a message in a channel it owns. */
+export type Admission =
+	| {
+			kind: "turn";
+			/**
+			 * When the channel is busy: whether the message is marked, and first offered to the
+			 * running turn with `steer`, which says whether the turn took it.
+			 */
+			busy?: {
+				steer?(): Promise<boolean>;
+				react(emoji: string): Promise<void>;
+				unreact(emoji: string): Promise<void>;
+			};
+			/** The turn, run in the channel's queue. */
+			run(): Promise<void>;
+			/** The log line when the turn throws. */
+			failure: string;
+	  }
+	| {
+			kind: "background";
+			turn: BackgroundTurn;
+			/** Called when the turn did not run. */
+			unanswered(outcome: ScheduledOutcome): void;
+	  };
+
+/**
+ * One plugin's channels. The router asks the claims by descending priority, then registration
+ * order, and the first that owns a channel decides everything there: a message it does not
+ * admit is dropped, never passed to a lower claim. Each operation runs inside the channel's
+ * queue, so none of them queues itself.
+ */
+export interface ChannelClaim {
+	name: string;
+	priority: number;
+	/** Whether the claim owns the channel; `guildId` is the message's server, when routing one. */
+	owns(channel: ChannelKey, guildId?: string): boolean;
+	/** What to do with a message in an owned channel; undefined drops it. */
+	admit(message: InboundMessage): Admission | undefined;
+	/** A background turn in an owned channel; a claim without one skips them. */
+	background?(turn: BackgroundTurn): Promise<ScheduledOutcome>;
+	/** Starts the channel's conversation over, saying whose it was. */
+	startFresh(channel: ChannelKey): Promise<string>;
+	/** Removes the channel's conversation for good; a claim without one refuses. */
+	deleteConversation?(channel: ChannelKey): Promise<void>;
+	/** Reports of work started in an owned channel stay in it instead of opening a thread. */
+	postsInPlace?: boolean;
+}
+
+/** The conversations of every claimed channel, through the channel queue. */
+export interface ConversationPort {
+	/** Never rejects; resolves when the message's turn is done or dropped. */
+	handle(message: InboundMessage): Promise<void>;
+	background(turn: BackgroundTurn): Promise<ScheduledOutcome>;
+	/** Waits for the channel's running turn, then starts its conversation over; says whose it was. */
+	startFresh(channel: ChannelKey): Promise<string>;
+	/** `busy` while a turn runs or waits in the channel. */
+	deleteConversation(channel: ChannelKey): Promise<"deleted" | "busy">;
+	/** Stops the channel's running turn; false when none runs. */
+	stop(channel: ChannelKey): boolean;
+	/** Whether reports of work started in the channel stay in it, by its owner's policy. */
+	postsInPlace(channel: ChannelKey): boolean;
+}
+
+/** The host's channel queue, as plugins use it. */
+export interface QueuePort {
+	run<T>(channel: ChannelKey, task: () => Promise<T>): Promise<T>;
+	/** Tasks of the channel running or waiting. */
+	size(channel: ChannelKey): number;
+	/** Channels with a task running or waiting. */
+	busy(): ChannelKey[];
+	/** Called whenever a channel's count of running and waiting tasks changes. */
+	onChange(listener: (channel: ChannelKey) => void): void;
+}

package/src/core/contract/discord.ts

@@ -0,0 +1,33 @@
+import type {
+	APIApplicationCommandSubcommandGroupOption,
+	APIApplicationCommandSubcommandOption,
+	Interaction,
+	InteractionContextType,
+	RESTPostAPIChatInputApplicationCommandsJSONBody,
+} from "discord.js";
+
+/** A group of slash commands and the components they post, handled together. */
+export interface InteractionModule {
+	/** Top-level commands of its own; never the configured root command. */
+	commands(): RESTPostAPIChatInputApplicationCommandsJSONBody[];
+	/** Resolves true when this module handled the interaction. */
+	handle(interaction: Interaction): Promise<boolean>;
+}
+
+/** A subcommand or subcommand group under the root command. */
+export type RootOption =
+	| APIApplicationCommandSubcommandOption
+	| APIApplicationCommandSubcommandGroupOption;
+
+/** A plugin's interactions: its module, and the subcommands it adds under the root command. */
+export interface InteractionContribution {
+	module: InteractionModule;
+	rootOptions?: readonly RootOption[];
+}
+
+/** The one root command every plugin's subcommands go under, such as `/roundtable`. */
+export interface CommandRoot {
+	name: string;
+	description: string;
+	contexts: readonly InteractionContextType[];
+}

package/src/core/contract/providers.ts

@@ -0,0 +1,67 @@
+/** A choice among named options; the answer is one option's name. */
+export interface ChoiceQuestion {
+	type: "choice";
+	instructions: string;
+	criteria: Record<string, string>;
+}
+
+export interface ChoiceAnswer {
+	choice: string;
+	confidence: number;
+}
+
+/** A yes-or-no question; the answer is the probability of yes. */
+export interface YesNoQuestion {
+	type: "yesno";
+	instructions: string;
+	criteria?: { true?: string; false?: string };
+}
+
+/** An ordinal question; the answer is a probability for each criterion, in order. */
+export interface ScoreQuestion {
+	type: "score";
+	instructions: string;
+	criteria: readonly string[];
+}
+
+/**
+ * Small judgments about a state: whether a reply approves held actions, how hard a turn is,
+ * which agents a group message concerns. Every method throws when it cannot answer; callers
+ * fall back to their own default.
+ */
+export interface Judge {
+	askYesNo(
+		state: Record<string, unknown>,
+		questions: Record<string, YesNoQuestion>,
+	): Promise<Record<string, number>>;
+	askChoice(
+		state: Record<string, unknown>,
+		name: string,
+		question: ChoiceQuestion,
+	): Promise<ChoiceAnswer>;
+	/** Probabilities indexed like the criteria. */
+	askScore(
+		state: Record<string, unknown>,
+		name: string,
+		question: ScoreQuestion,
+	): Promise<number[]>;
+}
+
+/** An image to draw from. */
+export interface ReferenceImage {
+	/** Base64 bytes. */
+	data: string;
+	mimeType: string;
+}
+
+/** Draws one image from a prompt and reference images; returns PNG or other decodable bytes. */
+export type ImageDrawer = (
+	prompt: string,
+	references: readonly ReferenceImage[],
+) => Promise<Uint8Array>;
+
+/** The replaceable parts the core runs on; a plugin provides at most the ones it replaces. */
+export interface Providers {
+	judge: Judge;
+	images: ImageDrawer;
+}

package/src/core/db/guild-scope.ts

@@ -0,0 +1,53 @@
+import type { SQL } from "bun";
+
+/** A table of the agent server and the columns that make a row unique inside one guild. */
+export interface GuildTable {
+	table: string;
+	key: readonly string[];
+}
+
+/** Serializes concurrent boots of the same migration. */
+const LOCK = 7284912301;
+
+/**
+ * Gives every row of the tables its guild and makes the guild part of the primary key, so
+ * names are unique per guild. Rows without a guild belong to `guildId`, the guild the process
+ * is configured for; rows of another guild are never touched. Idempotent, and all or nothing.
+ */
+export async function scopeToGuild(
+	sql: SQL,
+	guildId: string,
+	tables: readonly GuildTable[],
+): Promise<void> {
+	await sql.begin(async (tx) => {
+		await tx`SELECT pg_advisory_xact_lock(${LOCK})`;
+		for (const { table, key } of tables) {
+			await tx.unsafe(
+				`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS guild_id text`,
+			);
+			await tx.unsafe(
+				`UPDATE ${table} SET guild_id = $1 WHERE guild_id IS NULL`,
+				[guildId],
+			);
+			await tx.unsafe(
+				`ALTER TABLE ${table} ALTER COLUMN guild_id SET NOT NULL`,
+			);
+			await tx.unsafe(`
+				DO $migration$
+				DECLARE pk text;
+				BEGIN
+					SELECT c.conname INTO pk FROM pg_constraint c
+					WHERE c.conrelid = '${table}'::regclass AND c.contype = 'p'
+						AND NOT EXISTS (
+							SELECT 1 FROM pg_attribute a
+							WHERE a.attrelid = c.conrelid AND a.attnum = ANY (c.conkey)
+								AND a.attname = 'guild_id');
+					IF pk IS NOT NULL THEN
+						EXECUTE format('ALTER TABLE ${table} DROP CONSTRAINT %I', pk);
+						ALTER TABLE ${table} ADD PRIMARY KEY (guild_id, ${key.join(", ")});
+					END IF;
+				END
+				$migration$`);
+		}
+	});
+}