pi-roundtable 0.1.0 → 0.2.0

package/src/core/contract/channels.ts

@@ -1,3 +1,4 @@
+import type { Locale } from "../i18n/index.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Tier } from "../speakers.ts";
 
@@ -19,15 +20,20 @@ export interface InboundMessage {
 	/** 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. */
+	/** The roles the author holds in the message's space; 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;
+	/**
+	 * The server or workspace the channel belongs to, in the surface's own ids; absent in a
+	 * direct conversation.
+	 */
+	space?: string;
 	isDirect: boolean;
-	/** The server the message was posted in; absent in direct messages. */
-	guildId?: string;
+	/**
+	 * Set when an integration posted the message, such as a Discord webhook; its name is
+	 * `authorName`. `own` says the integration is one the assistant posts through itself, such as an
+	 * agent's voice.
+	 */
+	integration?: { id: string; own: boolean };
 	mentionsBot: boolean;
 	/** The message replies to one of the bot's messages. */
 	repliesToBot: boolean;
@@ -44,8 +50,9 @@ export interface InboundMessage {
 	/** 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;
+		/** The channel the message was forwarded from. */
+		source: ChannelKey;
+		/** A link to the original message. */
 		url: string;
 	};
 }
@@ -60,11 +67,30 @@ export type ScheduledOutcome =
 	| { status: "failed"; error: string }
 	| { status: "skipped"; reason: string };
 
+/**
+ * Whose turn a schedule or a delegated task asks for, contributed by the plugin whose claim
+ * answers it. The target also sets the limits of what may be scheduled or delegated for it, so a
+ * channel open to many people can be held tighter than the owner's own.
+ */
+export interface BackgroundTarget {
+	/** Stored on schedules and delegated jobs; unique across plugins, as a persona's kind is. */
+	name: string;
+	/** How lists such as `/<root> schedule` name it, in the host's locale. */
+	label(locale: Locale): string;
+	/** Limits of the schedules made for it; absent, nothing may be scheduled for it. */
+	schedules?: { perChannel: number; promptChars: number; aheadDays: number };
+	/** Limits of the delegated tasks reporting to it; absent, nothing may be delegated to it. */
+	delegation?: { maxRunning: number };
+}
+
 /** 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";
+	/**
+	 * The name of the `BackgroundTarget` the turn is for. The router skips a turn whose target no
+	 * plugin contributes, and a claim skips one it does not serve.
+	 */
+	target: string;
 	author: { id: string; name: string };
 	/**
 	 * The tier the turn runs at, which is its creator's when a person set it up; absent for
@@ -73,10 +99,17 @@ export interface BackgroundTurn {
 	tier?: Tier;
 	turnId: string;
 	text: string;
-	/** It delivers a report the owner is waiting for, so it may ask him on cards. */
+	/** It delivers a report the owner is waiting for, so it may ask them on cards. */
 	report?: boolean;
 }
 
+/**
+ * Whose conversation a channel holds, as the claim that owns it names it when `startFresh` says
+ * whose it was: any string, such as "owner" or "study". The host reads none of them, so a plugin
+ * narrows the kinds of its own claims itself.
+ */
+export type ConversationKind = string;
+
 /** What a claim does with a message in a channel it owns. */
 export type Admission =
 	| {
@@ -111,14 +144,19 @@ export type Admission =
 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;
+	/** Whether the claim owns the channel; `space` is the message's space, when routing one. */
+	owns(channel: ChannelKey, space?: 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>;
+	/**
+	 * Stops the channel's running turn; true when one was running. The router asks only the claim
+	 * that owns the channel, and a claim without `stop` has nothing to stop there.
+	 */
+	stop?(channel: ChannelKey): boolean;
 	/** 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. */
@@ -130,6 +168,8 @@ 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>;
+	/** A contributed background target, read when used; undefined when no plugin contributes it. */
+	target(name: string): BackgroundTarget | undefined;
 	/** 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. */

package/src/core/contract/providers.ts

@@ -1,3 +1,5 @@
+import type { RuntimeFactory } from "./runtime.ts";
+
 /** A choice among named options; the answer is one option's name. */
 export interface ChoiceQuestion {
 	type: "choice";
@@ -64,4 +66,19 @@ export type ImageDrawer = (
 export interface Providers {
 	judge: Judge;
 	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.
+	 */
+	runtime: RuntimeFactory;
+}
+
+/**
+ * Each slot as the host resolved it, and which slots a plugin fills. A slot no plugin fills holds
+ * the core's default, and `filled` is how a caller tells that default from a provider without
+ * calling it.
+ */
+export interface ResolvedProviders extends Providers {
+	readonly filled: ReadonlySet<keyof Providers>;
 }

package/src/core/contract/runtime.ts

@@ -0,0 +1,138 @@
+import type { TurnAttachments } from "../domain/attachment.ts";
+import type {
+	ChannelKey,
+	PendingConfirmation,
+	TranscriptEntry,
+	TurnResult,
+} from "../domain/conversation.ts";
+import type { OwnerPrompts } from "../domain/owner-prompts.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import type { Logger } from "../log.ts";
+import type { ThinkingSetting } from "../models.ts";
+import type { HostEnv, LinkedSessions } from "../plugin.ts";
+import type { AgentTurnScope } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+import type { ToolTiers } from "../tool-tiers.ts";
+import type { Judge } from "./providers.ts";
+
+/** A conversation's context use after its latest turn. */
+export interface ContextUse {
+	/** Null right after a compaction, until the next model response. */
+	tokens: number | null;
+	contextWindow: number;
+}
+
+/**
+ * Runs the conversations of the agent server, and of every claim that runs turns through
+ * `context.turns`: one persistent conversation per channel key (an agent's conversation has the
+ * key of its `AgentTurnScope.session`), its turns, its held actions, and its history. A plugin
+ * replaces the whole runtime by filling the `runtime` provider slot; the default runs Pi.
+ */
+export interface AgentRuntime {
+	/**
+	 * Runs one turn and returns how it ended. A turn that cannot run is `{ ok: false }`; a throw is
+	 * settled into a failed result by the caller.
+	 */
+	runTurn(request: TurnRequest): Promise<TurnResult>;
+	/**
+	 * Adds the message to the conversation's running turn when that turn is steerable and holds no
+	 * actions; false when the message must wait for its own turn.
+	 */
+	steer(
+		conversation: ChannelKey,
+		text: string,
+		attachments: TurnAttachments,
+		/** The message's author; a turn another speaker started takes no steering from them. */
+		speakerId?: string,
+	): Promise<boolean>;
+	/** Aborts the conversation's running turn and drops what was steered into it; false when none runs. */
+	stop(conversation: ChannelKey): boolean;
+	/** Archives a conversation and drops its held actions; called between turns. */
+	startFresh(conversation: ChannelKey): Promise<void>;
+	/** Like `startFresh`, but removes the conversation and every archive of it for good; called between turns. */
+	deleteConversation(conversation: ChannelKey): Promise<void>;
+	/** The conversation's held actions known in memory since startup. */
+	pendingConfirmation(
+		conversation: ChannelKey,
+	): PendingConfirmation | undefined;
+	/** The conversation's held actions, restored from the store after a restart. */
+	heldActions(
+		conversation: ChannelKey,
+	): Promise<PendingConfirmation | undefined>;
+	recentTranscript(
+		conversation: ChannelKey,
+		limit: number,
+	): Promise<TranscriptEntry[]>;
+	/** Undefined when unknown; the team status shows no context bar for the conversation then. */
+	contextUsage?(conversation: ChannelKey): ContextUse | undefined;
+	/** Runs in the host's preflight, before anything starts; a throw stops the boot. */
+	preflight?(): Promise<void>;
+	/** Runs when the host stops the agent server's runtime service. */
+	dispose?(): Promise<void> | void;
+}
+
+/** A skill file a session loads; only its name and description enter the prompt. */
+export interface LoadedSkill {
+	name: string;
+	description: string;
+	file: string;
+}
+
+/** The agent server's per-agent settings, which a runtime reads when it runs an agent's turn. */
+export interface AgentSessions {
+	/** The shell's working directory, shared by every agent; writes outside it are held. */
+	workDir: string;
+	/**
+	 * The skills the agent carries, read at the start of every run; a change rebuilds its
+	 * sessions, keeping their history.
+	 */
+	skills(name: string): readonly LoadedSkill[];
+	/** The agent's model (`<provider>/<id>`) and thinking setting, read at the start of every run. */
+	modelOf(name: string): { model: string; thinking: ThinkingSetting };
+	/** The channel the scope's turns run in: the group's for a seat in one, else the agent's own. */
+	turnChannel(scope: AgentTurnScope): ChannelKey;
+}
+
+/** Where a runtime keeps each conversation's held actions, so they survive a restart. */
+export interface HeldActionStore {
+	/** The held actions stored for the conversation, if any. */
+	load(conversation: ChannelKey): Promise<PendingConfirmation | undefined>;
+	/** Stores the conversation's held actions; `undefined` clears them. */
+	save(
+		conversation: ChannelKey,
+		held: PendingConfirmation | undefined,
+	): Promise<void>;
+}
+
+/** What the agent server hands a runtime provider when it builds the runtime. */
+export interface RuntimeDeps {
+	logger: Logger;
+	/** The host's locale and time zone. */
+	env: HostEnv;
+	/** Who the conversations serve. */
+	owner: { id: string; name: string };
+	/**
+	 * The linked session parts: hold rules, packages, session tools, and personas. Read once the
+	 * host has linked them, from the preflight on; calling it during the factory throws.
+	 */
+	sessions(): LinkedSessions;
+	/** What each tool needs; plugin tools are added when the host links, so ask at use time. */
+	toolTiers: ToolTiers;
+	/**
+	 * The owner's approval and question prompts in a conversation, from its chat surface; undefined
+	 * when the surface has none, and the action then waits for the owner's next message.
+	 */
+	prompts(
+		conversation: ChannelKey,
+		speaker?: Speaker,
+	): OwnerPrompts | undefined;
+	/** The agent server's per-agent settings, for agent turns. */
+	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. */
+export type RuntimeFactory = (deps: RuntimeDeps) => AgentRuntime;

package/src/core/contract/services.ts

@@ -0,0 +1,45 @@
+/**
+ * A typed name for a service one plugin provides and other plugins read. Two keys with one `id`
+ * are the same service, so a key survives being imported through two copies of a package.
+ */
+export interface ServiceKey<T> {
+	/** Unique across plugins, such as `"roundtable.schedules"` or `"my-notes.index"`. */
+	readonly id: string;
+	/** Type only; never set. Ties the key to the service it names, so keys of different services stay apart. */
+	readonly __service?: () => T;
+	/**
+	 * What to tell a plugin that reads the service while no registered plugin provides it, such as
+	 * how to switch the addon that provides it on. Without one the host gives its generic advice.
+	 */
+	readonly absent?: string;
+}
+
+/** Makes a key. The id is what the host matches on; give it a prefix of your own, such as your plugin's name. */
+export function serviceKey<T>(
+	id: string,
+	options: { absent?: string } = {},
+): ServiceKey<T> {
+	if (typeof id !== "string" || id.trim() === "")
+		throw new TypeError(
+			`a service key needs an id, a non-empty string such as "my-notes.index"; got ${JSON.stringify(id)}.`,
+		);
+	return Object.freeze(
+		options.absent === undefined ? { id } : { id, absent: options.absent },
+	);
+}
+
+/** What a plugin provides and reads through `PluginContext.services`. */
+export interface Services {
+	/** The service, or throws a PluginError naming the key and the plugin to register first when it is not provided yet. */
+	get<T>(key: ServiceKey<T>): T;
+	/**
+	 * The service, or undefined when no registered plugin declares it, such as an addon switched off.
+	 * Throws like `get` when a plugin declares it but has not been set up yet: that is order, not absence.
+	 */
+	find<T>(key: ServiceKey<T>): T | undefined;
+	/**
+	 * Provides a service the plugin declares in `provides`; only while the plugin's setup runs, and
+	 * once per key.
+	 */
+	provide<T>(key: ServiceKey<T>, value: T): void;
+}

package/src/core/contract/surface.ts

@@ -0,0 +1,88 @@
+import type { OutboundReply } from "../domain/conversation.ts";
+import type { OwnerPrompts } from "../domain/owner-prompts.ts";
+import { PluginError } from "../errors.ts";
+import type { ChannelKey } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+import type { InboundMessage } from "./channels.ts";
+
+/**
+ * Splits a channel key, `<surface>:<id>`, at its first colon: the surface names the chat network
+ * that owns the channel, such as `discord`, and the id is that network's own, and may contain colons.
+ * Throws PluginError for a key without a surface.
+ */
+export function parseChannelKey(key: ChannelKey): {
+	surface: string;
+	id: string;
+} {
+	const at = typeof key === "string" ? key.indexOf(":") : -1;
+	if (at <= 0)
+		throw new PluginError(
+			`"${String(key)}" is not a channel key. A key is <surface>:<id>, such as discord:123.`,
+		);
+	return { surface: key.slice(0, at), id: key.slice(at + 1) };
+}
+
+/** The key of a channel on a surface; the inverse of `parseChannelKey`. */
+export function channelKey(surface: string, id: string): ChannelKey {
+	if (surface === "" || surface.includes(":"))
+		throw new PluginError(
+			`"${surface}" is not a surface name. A surface is a non-empty word without a colon, such as discord.`,
+		);
+	return `${surface}:${id}`;
+}
+
+/**
+ * One chat network the host talks through. The host ships Discord's; a plugin may contribute
+ * another with `surfaces`. A surface serves the channels whose key starts with its `surface`
+ * prefix, and only those reach its methods.
+ */
+export interface ChatSurface {
+	/** The key prefix of this surface's channels, such as "discord"; unique per host. */
+	readonly surface: string;
+	/**
+	 * Connects and delivers every incoming message; the host passes its conversation router. A
+	 * message whose channel key has another prefix is logged and dropped.
+	 */
+	start(deliver: (message: InboundMessage) => void): Promise<void>;
+	/** Runs when the host stops, after the services started later have stopped. */
+	stop?(): Promise<void>;
+	sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void>;
+	/** Shows a typing indicator until the returned function is called; absent = none shown. */
+	startTyping?(channel: ChannelKey): () => void;
+	/**
+	 * Shows the owner a stop control until the returned function is called; it calls
+	 * `conversations.stop(channel)` when used. Absent = none shown.
+	 */
+	showStop?(channel: ChannelKey): () => void;
+	/** Adds or removes the bot's reaction on a message; failures are logged, never thrown. */
+	react?(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
+	unreact?(
+		channel: ChannelKey,
+		messageId: string,
+		emoji: string,
+	): Promise<void>;
+	/**
+	 * How the owner approves held actions or answers ask_user in a running turn; undefined, or
+	 * absent, = the action is held until the owner's next message.
+	 */
+	prompts?(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+}
+
+/**
+ * Every contributed surface, chosen by the prefix of a channel's key. Calls during setup throw
+ * NotLinkedError, because the surfaces are collected once every plugin is set up.
+ */
+export interface SurfacePort {
+	/** The surface that serves the channel's prefix; undefined when none does. */
+	of(channel: ChannelKey): ChatSurface | undefined;
+	/** Throws PluginError naming the prefix when no surface serves it. */
+	sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void>;
+	/** A no-op when no surface serves the channel or its surface shows none. */
+	startTyping(channel: ChannelKey): () => void;
+	/** A no-op when no surface serves the channel or its surface shows none. */
+	showStop(channel: ChannelKey): () => void;
+	react(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
+	unreact(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
+	/** The owner's prompts in the channel; undefined when its surface has none. */
+	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+}

package/src/core/db/migrations.ts

@@ -1,12 +1,29 @@
-import { SQL } from "bun";
+import { SQL, type TransactionSQL } from "bun";
 import { MigrationError, PluginError } from "../errors.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
 
-/** Idempotent DDL a plugin's tables need; every boot runs it again over the existing schema. */
+/** A plugin's tables, as DDL its `up` runs. */
 export interface Migration {
 	name: string;
+	/**
+	 * "once" (the default): the ledger records it, so it runs one time over a database and never
+	 * again. "every-boot": runs at every boot and is never recorded; it must be idempotent, which
+	 * suits a migration that converges data an older build may have written since.
+	 */
+	runs?: "once" | "every-boot";
 	up(sql: SQL): Promise<void>;
 }
 
+/** What one boot's migrations did, each entry a ledger id (`<plugin>/<migration>`). */
+export interface MigrationReport {
+	/** The "once" migrations that ran now and were recorded. */
+	applied: string[];
+	/** The "once" migrations the ledger already held. */
+	skipped: string[];
+	/** The "every-boot" migrations that ran. */
+	everyBoot: string[];
+}
+
 /**
  * The host's one connection pool. PostgreSQL's 100 connections are shared with the other services on the same server,
  * so the pool stays small and closes idle connections; Bun's defaults (10, never closed)
@@ -16,7 +33,23 @@ export function openPool(databaseUrl: string): SQL {
 	return new SQL(databaseUrl, { max: 10, idleTimeout: 60 });
 }
 
-/** Runs the migrations in order; a repeated name is a plugin bug, a failing one stops the boot. */
+/**
+ * The transaction as a migration sees the pool: a migration that opens its own transaction
+ * with `begin` gets a savepoint of the running one, which PostgreSQL nests.
+ */
+export function nested(transaction: TransactionSQL): SQL {
+	return new Proxy(transaction, {
+		get(target, property) {
+			if (property === "begin")
+				return (...args: Parameters<TransactionSQL["savepoint"]>) =>
+					target.savepoint(...args);
+			const value: unknown = Reflect.get(target, property);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}
+
+/** Runs each migration in order, none of them recorded; a repeated name is a plugin bug, a failing one stops. Test setup uses it for tables a test drops and rebuilds. */
 export async function migrate(
 	sql: SQL,
 	migrations: readonly Migration[],
@@ -35,3 +68,85 @@ export async function migrate(
 		}
 	}
 }
+
+const LEDGER = "roundtable_migrations";
+
+/** The lock key for one name; two hosts booting together queue on it instead of racing. */
+const lockOf = (name: string) => `pi-roundtable:migration:${name}`;
+
+/**
+ * Runs every plugin's migrations in plugin order, then declaration order, the way a boot does. A
+ * "once" migration runs inside its own transaction under an advisory lock, and the ledger row is
+ * written in that transaction, so a migration that failed leaves no record and two hosts booting at
+ * once apply it one time in total. An "every-boot" migration runs each time and is not recorded.
+ */
+export async function runMigrations(
+	sql: SQL,
+	plugins: readonly Pick<RoundtablePlugin, "name" | "migrations">[],
+): Promise<MigrationReport> {
+	const steps = plugins.flatMap((plugin) =>
+		(plugin.migrations ?? []).map((migration) => ({
+			id: `${plugin.name}/${migration.name}`,
+			plugin: plugin.name,
+			migration,
+		})),
+	);
+	const ids = new Set<string>();
+	for (const { id } of steps) {
+		if (ids.has(id)) throw new PluginError(`migration ${id} is declared twice`);
+		ids.add(id);
+	}
+	const report: MigrationReport = { applied: [], skipped: [], everyBoot: [] };
+	if (steps.length === 0) return report;
+
+	await sql.begin(async (tx) => {
+		await tx`SELECT pg_advisory_xact_lock(hashtextextended(${lockOf("ledger")}, 0))`;
+		await tx.unsafe(`
+			CREATE TABLE IF NOT EXISTS ${LEDGER} (
+				id text PRIMARY KEY,
+				plugin text NOT NULL,
+				name text NOT NULL,
+				applied_at timestamptz NOT NULL DEFAULT now()
+			)`);
+	});
+
+	for (const { id, plugin, migration } of steps) {
+		try {
+			if (migration.runs === "every-boot") {
+				await migration.up(sql);
+				report.everyBoot.push(id);
+				continue;
+			}
+			const ran = await sql.begin(async (tx) => {
+				await tx`SELECT pg_advisory_xact_lock(hashtextextended(${lockOf(id)}, 0))`;
+				const [recorded] =
+					await tx`SELECT 1 FROM roundtable_migrations WHERE id = ${id}`;
+				if (recorded) return false;
+				await migration.up(nested(tx));
+				await tx`INSERT INTO roundtable_migrations (id, plugin, name) VALUES (${id}, ${plugin}, ${migration.name})`;
+				return true;
+			});
+			(ran ? report.applied : report.skipped).push(id);
+		} catch (error) {
+			throw new MigrationError(id, error);
+		}
+	}
+	return report;
+}
+
+/**
+ * Runs these plugins' migrations over the database at `url` with the ledger and the lock a boot
+ * uses, then closes its connection. Pass the plugins, with the names, the host runs: the ledger ids
+ * come from them, so another name would record the same tables a second time under it.
+ */
+export async function migrateDatabase(
+	url: string,
+	plugins: readonly Pick<RoundtablePlugin, "name" | "migrations">[],
+): Promise<MigrationReport> {
+	const pool = new SQL(url, { max: 2 });
+	try {
+		return await runMigrations(pool, plugins);
+	} finally {
+		await pool.close();
+	}
+}