pi-roundtable 0.1.0

package/src/core/host.ts

@@ -0,0 +1,297 @@
+import type { SQL } from "bun";
+import type { ConversationPort } from "./contract/channels.ts";
+import type { CommandRoot } from "./contract/discord.ts";
+import { migrate, openPool } from "./db/migrations.ts";
+import { type DrainOptions, waitUntilIdle } from "./drain.ts";
+import { MigrationError, NotLinkedError, PluginError } from "./errors.ts";
+import { EventBus } from "./events.ts";
+import { HttpListeners, type ListenerConfig } from "./http/listeners.ts";
+import type { JudgeModel } from "./judging/model-judge.ts";
+import type { Logger } from "./log.ts";
+import type {
+	AgentServerOutcome,
+	LinkedSessions,
+	RoundtablePlugin,
+} from "./plugin.ts";
+import {
+	collectContributions,
+	emptyRegistry,
+	linkSessions,
+	type Registry,
+} from "./registry/contributions.ts";
+import { composeInteractions } from "./registry/interactions.ts";
+import { resolveProviders } from "./registry/providers.ts";
+import { ChannelQueue } from "./routing/channel-queue.ts";
+import { ChannelRouter } from "./routing/channel-router.ts";
+import { CoreRegistry } from "./services.ts";
+import { type ToolTierTable, toolTiers } from "./tool-tiers.ts";
+
+export interface RoundtableOptions {
+	logger: Logger;
+	/**
+	 * The root command the plugins' subcommands go under; the composed commands go to the plugins'
+	 * `useCommands` before any service starts, since Discord registers them as it connects.
+	 */
+	commands?: {
+		root: CommandRoot;
+	};
+	/** The HTTP listeners plugins attach routes to. */
+	listeners?: readonly ListenerConfig[];
+	/** How long a bare forward waits for the message it follows. */
+	conversations?: {
+		forwardJoinMs?: number;
+	};
+	/** The model the default judge asks, when no plugin provides a judge. */
+	judgeModel?: JudgeModel;
+	/** What each tool needs: the operator's settings, with the plugins' tools added when the host links. */
+	toolTiers?: ToolTierTable;
+	/** The database the plugins' migrations and stores use; the host owns its one pool. */
+	database?: { url: string };
+	/** Receives the work a shutdown drain gave up on, before any service stops. */
+	aborted?: (left: string[]) => Promise<void>;
+	/** The drain's limit and clock; tests shorten them. */
+	drain?: Omit<DrainOptions, "busy">;
+	exit?: (code: number) => void;
+}
+
+type Attempt = { ok: true } | { ok: false; error: unknown };
+
+/** Runs one step whose failure the caller reports and moves past. */
+async function attempt(step: () => Promise<void> | void): Promise<Attempt> {
+	try {
+		await step();
+		return { ok: true };
+	} catch (error) {
+		return { ok: false, error };
+	}
+}
+
+/** Starts the agent server, then tells every plugin how that went; a failing handler never stops the others. */
+async function startAgentServer(
+	start: () => Promise<void>,
+	handlers: Registry["handlers"],
+	logger: Logger,
+): Promise<void> {
+	const started = await attempt(start);
+	// The rest of the process runs on without the agent server's new channels.
+	if (started.ok) logger.info("agent server ready");
+	else logger.error({ err: started.error }, "agent server did not start");
+	const outcome: AgentServerOutcome = started.ok ? "ready" : "failed";
+	for (const { plugin, events } of handlers) {
+		const handled = await attempt(() => events.agentServer?.(outcome));
+		if (!handled.ok)
+			logger.error(
+				{ plugin, err: handled.error },
+				"agent server handler failed",
+			);
+	}
+}
+
+/**
+ * The process around the plugins: it sets them all up, links what they add (session parts,
+ * commands, HTTP routes) and runs the preflight, then starts their services in order and the
+ * HTTP listeners last, and starts the agent server. Nothing reaches Discord or a listener unless
+ * every setup, link, and the preflight succeeded. On shutdown it waits until no work runs or
+ * waits before closing the listeners and stopping the services in reverse.
+ */
+// pi-lens-ignore: large-class
+export class Roundtable {
+	readonly #options: RoundtableOptions;
+	readonly #plugins: readonly RoundtablePlugin[];
+	#registry: Registry = emptyRegistry();
+	#sessions: LinkedSessions | undefined;
+	#router: ChannelRouter | undefined;
+	#listeners: HttpListeners | undefined;
+	#pool: SQL | undefined;
+	readonly #queue = new ChannelQueue();
+	readonly #tiers: ToolTierTable;
+	readonly #events: EventBus;
+	readonly #core = new CoreRegistry();
+
+	constructor(
+		options: RoundtableOptions,
+		plugins: readonly RoundtablePlugin[],
+	) {
+		this.#options = options;
+		this.#plugins = plugins;
+		this.#tiers = options.toolTiers ?? toolTiers();
+		this.#events = new EventBus(options.logger);
+	}
+
+	/** The claimed channels' conversations; every call before linking throws NotLinkedError. */
+	#conversations(): ConversationPort {
+		const router = () => {
+			if (!this.#router)
+				throw new NotLinkedError(
+					"conversations are linked once every plugin is set up. Use them from a service's start or from a handler, not during setup.",
+				);
+			return this.#router;
+		};
+		return {
+			handle: (message) => router().handle(message),
+			background: (turn) => router().background(turn),
+			startFresh: (channel) => router().startFresh(channel),
+			deleteConversation: (channel) => router().deleteConversation(channel),
+			stop: (channel) => router().stop(channel),
+			postsInPlace: (channel) => router().postsInPlace(channel),
+		};
+	}
+
+	/**
+	 * Sets up every plugin, links what they add and runs the preflight, refusing any clash before
+	 * anything starts, then starts the services and opens the listeners; the agent server starts
+	 * in the background.
+	 */
+	async run(): Promise<void> {
+		const { logger, commands, listeners = [] } = this.#options;
+		const providers = resolveProviders(this.#plugins, this.#options.judgeModel);
+		await this.#migrate();
+		this.#registry = await collectContributions(
+			this.#plugins,
+			{
+				logger,
+				sessions: () => {
+					if (!this.#sessions)
+						throw new NotLinkedError(
+							"session parts are linked once every plugin is set up. Call sessions() from a service's start or from a handler, not during setup.",
+						);
+					return this.#sessions;
+				},
+				queue: this.#queue,
+				toolTiers: this.#tiers,
+				events: this.#events.sink,
+				conversations: this.#conversations(),
+				database: () => {
+					if (!this.#pool) throw new PluginError("no database is configured");
+					return this.#pool;
+				},
+				providers,
+				core: this.#core,
+				dashboard: () => {
+					if (!this.#sessions)
+						throw new NotLinkedError(
+							"dashboard lines are linked once every plugin is set up. Call dashboard() from a service's start or from a handler, not during setup.",
+						);
+					return this.#registry.dashboard;
+				},
+			},
+			this.#tiers,
+		);
+		const { interactions, routes, channels } = this.#registry;
+		this.#sessions = linkSessions(this.#registry);
+		this.#events.link(this.#registry.handlers);
+		this.#router = new ChannelRouter({
+			claims: channels,
+			queue: this.#queue,
+			stop: (channel) =>
+				this.#plugins.some((plugin) => plugin.stopTurn?.(channel) ?? false),
+			logger,
+			...(this.#options.conversations?.forwardJoinMs === undefined
+				? {}
+				: { forwardJoinMs: this.#options.conversations.forwardJoinMs }),
+		});
+		if (interactions.length > 0 && !commands)
+			throw new PluginError("interactions need a configured root command");
+		const composed =
+			commands && interactions.length > 0
+				? composeInteractions(commands.root, interactions)
+				: undefined;
+		const http = new HttpListeners(listeners, routes);
+		for (const plugin of this.#plugins) await plugin.preflight?.();
+		if (composed)
+			for (const plugin of this.#plugins) plugin.useCommands?.(composed);
+		for (const service of this.#registry.services) await service.start?.();
+		// Requests arrive only once everything they may reach is running.
+		http.start();
+		this.#listeners = http;
+		const agentServer = this.#agentServer();
+		if (agentServer)
+			void startAgentServer(agentServer, this.#registry.handlers, logger);
+	}
+
+	/** The one plugin's way to start the agent server; two plugins that start it are refused. */
+	#agentServer(): (() => Promise<void>) | undefined {
+		const starting = this.#plugins.filter((plugin) => plugin.agentServer);
+		const [first, second] = starting;
+		if (second)
+			throw new PluginError(
+				`plugins ${first?.name} and ${second.name} both start the agent server. Keep one.`,
+			);
+		return first?.agentServer?.bind(first);
+	}
+
+	/** Opens the pool and runs every plugin's migrations; a failure closes it again and stops the boot. */
+	async #migrate(): Promise<void> {
+		const migrations = this.#plugins.flatMap(
+			(plugin) => plugin.migrations ?? [],
+		);
+		const { database } = this.#options;
+		if (!database) {
+			if (migrations.length > 0)
+				throw new PluginError("migrations need a configured database");
+			return;
+		}
+		const pool = openPool(database.url);
+		try {
+			await migrate(pool, migrations);
+		} catch (error) {
+			await pool.close();
+			if (error instanceof MigrationError) {
+				const owner = this.#plugins.find((plugin) =>
+					plugin.migrations?.some(({ name }) => name === error.migration),
+				);
+				throw new PluginError(
+					`plugin ${owner?.name ?? "unknown"}: migration ${error.migration} failed: ${String(error.cause)}. Fix the migration or restore the database, then start again.`,
+					{ cause: error },
+				);
+			}
+			throw error;
+		}
+		this.#pool = pool;
+	}
+
+	/** Shuts down once idle when the process is asked to stop. */
+	listen(): void {
+		process.once("SIGTERM", () => void this.shutdown("SIGTERM"));
+		process.once("SIGINT", () => void this.shutdown("SIGINT"));
+	}
+
+	async shutdown(signal: string): Promise<void> {
+		const { logger, aborted, drain, exit = process.exit } = this.#options;
+		const { services } = this.#registry;
+		// Everything keeps serving until nothing runs or waits, so a deploy never cuts a turn short.
+		logger.info({ signal }, "shutting down once idle");
+		const left = await waitUntilIdle({
+			...drain,
+			busy: () => services.flatMap((service) => service.busy?.() ?? []),
+		});
+		if (left.length > 0) {
+			logger.warn(
+				{ aborted: left },
+				"still busy after the drain limit; aborting",
+			);
+			const recorded = await attempt(() => aborted?.(left));
+			if (!recorded.ok)
+				logger.error({ err: recorded.error }, "aborted work not recorded");
+		}
+		await this.#events.deliver("shutdown", left);
+		logger.info({ signal }, "shutting down");
+		// No request may reach a service that has stopped.
+		const closed = await attempt(() => this.#listeners?.stop());
+		if (!closed.ok)
+			logger.error({ err: closed.error }, "http listeners did not close");
+		for (const service of services.toReversed()) {
+			const stopped = await attempt(() => service.stop?.());
+			if (!stopped.ok)
+				logger.error(
+					{ service: service.name, err: stopped.error },
+					"service did not stop",
+				);
+		}
+		// Last, once nothing that queries it runs.
+		const released = await attempt(() => this.#pool?.close());
+		if (!released.ok)
+			logger.error({ err: released.error }, "database pool did not close");
+		exit(0);
+	}
+}

package/src/core/http/listeners.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PluginError } from "../errors.ts";
+import { HttpListeners, type HttpRoute, routeRequest } from "./listeners.ts";
+
+const answer =
+	(text: string, listener = "public", methods?: string[]) =>
+	(path: HttpRoute["path"]): HttpRoute => ({
+		name: `${text} ${JSON.stringify(path)}`,
+		listener,
+		path,
+		...(methods ? { methods } : {}),
+		handle: () => new Response(text),
+	});
+
+async function reply(
+	routes: HttpRoute[],
+	path: string,
+	method = "GET",
+): Promise<[number, string]> {
+	const response = await routeRequest(
+		routes,
+		new Request(`http://localhost${path}`, { method }),
+	);
+	return [response.status, await response.text()];
+}
+
+function refused(build: () => unknown): unknown {
+	try {
+		build();
+		return undefined;
+	} catch (error) {
+		return error;
+	}
+}
+
+describe("routeRequest", () => {
+	const routes = [
+		answer("personal")({ exact: "/mcp/personal" }),
+		answer("discord")({ prefix: "/mcp/discord/" }),
+		answer("avatar", "public", ["GET", "HEAD"])({ prefix: "/avatars/" }),
+	];
+
+	test("takes exact paths, prefixes, and listed methods only", async () => {
+		expect(await reply(routes, "/mcp/personal", "POST")).toEqual([
+			200,
+			"personal",
+		]);
+		expect(await reply(routes, "/mcp/personal", "DELETE")).toEqual([
+			200,
+			"personal",
+		]);
+		expect(await reply(routes, "/mcp/discord/abc", "POST")).toEqual([
+			200,
+			"discord",
+		]);
+		expect(await reply(routes, "/avatars/a.png")).toEqual([200, "avatar"]);
+		expect(await reply(routes, "/avatars/a.png", "POST")).toEqual([
+			404,
+			"Not found",
+		]);
+		expect(await reply(routes, "/mcp/personal/more", "POST")).toEqual([
+			404,
+			"Not found",
+		]);
+		expect(await reply(routes, "/app/")).toEqual([404, "Not found"]);
+	});
+});
+
+describe("HttpListeners", () => {
+	test("refuses routes one request could reach twice, and unknown listeners", () => {
+		const listeners = [
+			{ id: "public", socketPath: "/tmp/p.sock" },
+			{ id: "web", socketPath: "/tmp/w.sock" },
+		];
+		const build = (routes: HttpRoute[]) => () =>
+			new HttpListeners(listeners, routes);
+		expect(
+			refused(
+				build([
+					answer("a")({ prefix: "/mcp/" }),
+					answer("b")({ exact: "/mcp/personal" }),
+				]),
+			),
+		).toBeInstanceOf(PluginError);
+		expect(
+			refused(
+				build([
+					answer("a")({ prefix: "/app/" }),
+					answer("b")({ prefix: "/app/api/" }),
+				]),
+			),
+		).toBeInstanceOf(PluginError);
+		expect(
+			refused(build([answer("a", "elsewhere")({ exact: "/" })])),
+		).toBeInstanceOf(PluginError);
+		// Different listeners or methods never clash.
+		expect(
+			refused(
+				build([
+					answer("a")({ prefix: "/app/" }),
+					answer("b", "web")({ prefix: "/app/" }),
+					answer("c", "public", ["GET"])({ exact: "/x" }),
+					answer("d", "public", ["POST"])({ exact: "/x" }),
+				]),
+			),
+		).toBeUndefined();
+	});
+
+	test("each socket serves only its own routes, open to cloudflared", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "listeners-"));
+		const listeners = [
+			{ id: "public", socketPath: join(dir, "public.sock") },
+			{ id: "web", socketPath: join(dir, "web.sock") },
+		];
+		const http = new HttpListeners(listeners, [
+			answer("mcp")({ exact: "/mcp/personal" }),
+			answer("app", "web")({ prefix: "/app/" }),
+		]);
+		http.start();
+		const get = async (socket: string, path: string) => {
+			const response = await fetch(`http://localhost${path}`, {
+				unix: join(dir, socket),
+			});
+			return [response.status, await response.text()];
+		};
+		try {
+			expect(await get("public.sock", "/mcp/personal")).toEqual([200, "mcp"]);
+			expect(await get("public.sock", "/app/")).toEqual([404, "Not found"]);
+			expect(await get("web.sock", "/app/")).toEqual([200, "app"]);
+			expect(await get("web.sock", "/mcp/personal")).toEqual([
+				404,
+				"Not found",
+			]);
+			expect(statSync(join(dir, "web.sock")).mode & 0o777).toBe(0o666);
+		} finally {
+			http.stop();
+		}
+	});
+
+	test("serves a TCP listener with only its own routes", async () => {
+		// A free port, found by opening one and closing it again.
+		const probe = Bun.serve({ port: 0, fetch: () => new Response("") });
+		const port = probe.port ?? 0;
+		await probe.stop(true);
+		const http = new HttpListeners(
+			[{ id: "public", port, hostname: "127.0.0.1" }],
+			[answer("avatar")({ prefix: "/avatars/" })],
+		);
+		http.start();
+		try {
+			const get = async (path: string) => {
+				const response = await fetch(`http://127.0.0.1:${port}${path}`);
+				return [response.status, await response.text()];
+			};
+			expect(await get("/avatars/a.png")).toEqual([200, "avatar"]);
+			expect(await get("/elsewhere")).toEqual([404, "Not found"]);
+		} finally {
+			http.stop();
+		}
+	});
+});

package/src/core/http/listeners.ts

@@ -0,0 +1,151 @@
+import { chmodSync, rmSync } from "node:fs";
+import type { Server } from "bun";
+import { PluginError } from "../errors.ts";
+
+/** A handler a plugin attaches to one of the host's configured listeners. */
+export interface HttpRoute {
+	name: string;
+	/** The configured listener it attaches to; a route never creates one. */
+	listener: string;
+	path: { exact: string } | { prefix: string };
+	/** Omitted: every method, for a handler that answers the rest itself. */
+	methods?: readonly string[];
+	handle(request: Request): Response | Promise<Response>;
+}
+
+/** Where a listener serves: a unix socket, reached from outside through a tunnel, or a TCP port. */
+export type ListenerAddress =
+	| { socketPath: string }
+	| { port: number; hostname?: string };
+
+/** An address the host serves HTTP on, with the id routes name it by. */
+export type ListenerConfig = { id: string } & ListenerAddress;
+
+const pathOf = (route: HttpRoute) =>
+	"exact" in route.path ? route.path.exact : route.path.prefix;
+
+const matches = (route: HttpRoute, path: string) =>
+	"exact" in route.path
+		? path === route.path.exact
+		: path.startsWith(route.path.prefix);
+
+/** Whether one request could match both routes. */
+function overlaps(a: HttpRoute, b: HttpRoute): boolean {
+	const methods =
+		!a.methods || !b.methods || a.methods.some((m) => b.methods?.includes(m));
+	if (!methods) return false;
+	// Each side's path is a request path the other may match.
+	return matches(a, pathOf(b)) || matches(b, pathOf(a));
+}
+
+/** Refuses routes on unknown listeners, reused names, and any request two routes could both take. */
+function validate(
+	listeners: readonly ListenerConfig[],
+	routes: readonly HttpRoute[],
+): void {
+	const ids = new Set(listeners.map((l) => l.id));
+	if (ids.size !== listeners.length)
+		throw new PluginError("a listener is configured twice");
+	routes.forEach((route, index) => {
+		if (!ids.has(route.listener))
+			throw new PluginError(
+				`route ${route.name} needs listener ${route.listener}, which is not configured`,
+			);
+		for (const other of routes.slice(0, index)) {
+			if (other.name === route.name)
+				throw new PluginError(`route ${route.name} is registered twice`);
+			if (other.listener === route.listener && overlaps(other, route))
+				throw new PluginError(
+					`routes ${other.name} and ${route.name} overlap on listener ${route.listener}`,
+				);
+		}
+	});
+}
+
+/** Routes one listener's request; a request no route takes is 404. The URL is never logged, since paths may hold tokens. */
+export function routeRequest(
+	routes: readonly HttpRoute[],
+	request: Request,
+): Response | Promise<Response> {
+	// pi-lens-ignore: unchecked-throwing-call -- the server builds request.url, always an absolute URL
+	const path = new URL(request.url).pathname;
+	const route = routes.find(
+		(r) =>
+			matches(r, path) && (!r.methods || r.methods.includes(request.method)),
+	);
+	return route
+		? route.handle(request)
+		: new Response("Not found", { status: 404 });
+}
+
+/**
+ * Serves HTTP on a unix socket without Bun's 10-second idle timeout, which would cut long
+ * turns and quiet model streams. Bun 1.4.2 honors `idleTimeout` on unix sockets, but its
+ * types reject the option there, hence the cast. A stale socket file is removed first.
+ * (`shared/unix-server.ts` keeps its own copy for the party worker's image.)
+ */
+function serveUnix(
+	socketPath: string,
+	fetch: (request: Request) => Response | Promise<Response>,
+): Server<undefined> {
+	rmSync(socketPath, { force: true });
+	const options = { unix: socketPath, idleTimeout: 0, fetch };
+	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.
+	return Bun.serve(
+		options as unknown as Parameters<typeof Bun.serve>[0],
+	) as Server<undefined>;
+}
+
+/** Serves HTTP on a TCP port with the same idle setting as the unix sockets. */
+function serveTcp(
+	port: number,
+	hostname: string | undefined,
+	fetch: (request: Request) => Response | Promise<Response>,
+): Server<undefined> {
+	return Bun.serve({
+		port,
+		...(hostname ? { hostname } : {}),
+		idleTimeout: 0,
+		fetch,
+	});
+}
+
+/** The host's HTTP listeners, each serving only the routes attached to it. */
+// pi-lens-ignore: large-class — three members: validation in the constructor, start, and stop
+export class HttpListeners {
+	readonly #listeners: readonly ListenerConfig[];
+	readonly #routes: readonly HttpRoute[];
+	#servers: Server<undefined>[] = [];
+
+	/** Validates every route before any socket opens. */
+	constructor(
+		listeners: readonly ListenerConfig[],
+		routes: readonly HttpRoute[],
+	) {
+		validate(listeners, routes);
+		this.#listeners = listeners;
+		this.#routes = routes;
+	}
+
+	start(): void {
+		for (const listener of this.#listeners) {
+			const routes = this.#routes.filter(
+				(route) => route.listener === listener.id,
+			);
+			const handle = (request: Request) => routeRequest(routes, request);
+			if ("socketPath" in listener) {
+				this.#servers.push(serveUnix(listener.socketPath, handle));
+				// cloudflared runs as another user in its container.
+				chmodSync(listener.socketPath, 0o666);
+			} else {
+				this.#servers.push(serveTcp(listener.port, listener.hostname, handle));
+			}
+		}
+	}
+
+	/** Stops accepting at once and cuts open connections, such as event streams, without waiting on them. */
+	stop(): void {
+		for (const server of this.#servers) void server.stop(true);
+		this.#servers = [];
+	}
+}