pi-roundtable 0.7.19 → 0.9.0

package/src/core/discord/stop-button.ts

@@ -12,7 +12,7 @@ import type { CommandGuard, InteractionModule } from "./interaction-module.ts";
 
 export const STOP_BUTTON_ID = "roundtable:stop";
 
-/** The message a long turn shows: a stop button only the owner may press. */
+/** The message a long turn shows: a stop button only an owner may press. */
 export function stopPanel() {
 	return {
 		content: messages().stopNote,
@@ -29,13 +29,13 @@ export function stopPanel() {
 }
 
 export interface StopButtonOptions {
-	guard: Pick<CommandGuard, "isOwner">;
+	guard: Pick<CommandGuard, "allows">;
 	/** Stops the running turn of the channel the button was pressed in, through its claim. */
 	conversations: Pick<ConversationPort, "stop">;
 }
 
 /**
- * Answers a press of the stop button: only the owner stops the channel's turn, and the answer,
+ * Answers a press of the stop button: only an owner stops the channel's turn, and the answer,
  * visible only to whoever pressed, says whether one was running.
  */
 export function stopButtonModule(
@@ -46,7 +46,7 @@ export function stopButtonModule(
 		handle: async (interaction: Interaction) => {
 			if (!interaction.isButton() || interaction.customId !== STOP_BUTTON_ID)
 				return false;
-			const owner = options.guard.isOwner(interaction);
+			const owner = await options.guard.allows(interaction);
 			const stopped =
 				owner &&
 				options.conversations.stop(

package/src/core/domain/conversation.ts

@@ -26,6 +26,16 @@ export interface PendingConfirmation {
 	selectionId: string;
 	heldAt: Date;
 	calls: HeldCall[];
+	/**
+	 * The speaker whose turn held the calls, by their id on the surface. Besides the owners, only
+	 * they may approve them, at a tier that holds them; without one, the owners alone may.
+	 */
+	speakerId?: string;
+	/**
+	 * The principal of that speaker, who approves them on any of their identities; absent for
+	 * calls held before 0.9, which are matched by `speakerId`.
+	 */
+	principalId?: string;
 }
 
 /** A file produced for a reply; data is raw bytes, not a path or base64. */

package/src/core/domain/errors.ts

@@ -29,3 +29,8 @@ export class DelegationError extends Error {
 export class AgentError extends Error {
 	override name = "AgentError";
 }
+
+/** A principal, identity link, or role change that cannot be made; its message names what to fix. */
+export class IdentityError extends Error {
+	override name = "IdentityError";
+}

package/src/core/domain/ports.ts

@@ -3,9 +3,15 @@ import type { Speaker } from "../speakers.ts";
 import type { TurnAttachments } from "./attachment.ts";
 import type { ChannelKey } from "./conversation.ts";
 import type { InterimPosts } from "./interim.ts";
+import type { TurnProgress } from "./progress.ts";
 
 export type { AgentTurnScope };
 
+/** Who a turn's conversation belongs to. */
+export type TurnConversation =
+	| { visibility: "private"; principalId: string }
+	| { visibility: "shared" };
+
 export interface TurnRequest {
 	/** Where the turn's message arrived and its attachments are saved. */
 	channel: ChannelKey;
@@ -18,8 +24,18 @@ export interface TurnRequest {
 	confirmed?: boolean;
 	/** Set for a turn of an agent-server agent. */
 	agent?: AgentTurnScope;
-	/** The person the turn is for: who wrote the message, or who set up the work. */
-	speaker?: Speaker;
+	/**
+	 * The person the turn is for: who wrote the message, or who set up the work; the turn runs at
+	 * their tier. Required: a turn without one is refused, never run as the owner's. A plugin that
+	 * starts a turn on someone's behalf gets theirs from `IDENTITY.speakerFor`.
+	 */
+	speaker: Speaker;
+	/**
+	 * Who the conversation belongs to, as the host records it: `private` to one principal, or
+	 * `shared` by whoever its claim admits, which it is taken to be when absent. A private
+	 * conversation's prompts are its person's alone; a shared one's escalate to the owners.
+	 */
+	conversation?: TurnConversation;
 	/**
 	 * The conversation's kind, fixed when its session is made: the string a claim's `startFresh`
 	 * returns, which picks the persona of a non-agent conversation. "owner" when absent.
@@ -38,6 +54,11 @@ export interface TurnRequest {
 	 * hands the channel its reply goes to. Absent = only the final reply is posted.
 	 */
 	interim?: InterimPosts;
+	/**
+	 * Hears what the turn writes and which tools it runs, as it goes, until the turn ends. A runtime
+	 * without live progress never calls it.
+	 */
+	progress?: (event: TurnProgress) => void;
 }
 
 /** The judge's question and answer shapes. */
@@ -48,6 +69,16 @@ export type {
 	YesNoQuestion,
 } from "../contract/providers.ts";
 
+/** Sends a person a notice through their own channel; resolves false when they have none. */
+export interface Notifier {
+	notify(principalId: string, text: string): Promise<boolean>;
+}
+
+/**
+ * Sends the primary owner a direct message.
+ * @deprecated Since 0.9 there may be more than one owner: reach a person with a `Notifier`, such as
+ * `context.directChannels`. Goes away in 1.0.
+ */
 export interface OwnerNotifier {
 	notifyOwner(text: string): Promise<void>;
 }

package/src/core/domain/progress.ts

@@ -0,0 +1,10 @@
+/**
+ * What a running turn reports as it goes, for a surface that shows it live. Text arrives in
+ * chunks joined over a short interval; a tool is named with a short one-line preview of its
+ * arguments, never their full text, and ends with whether it succeeded. The final reply still
+ * arrives through `sendReply`.
+ */
+export type TurnProgress =
+	| { type: "text"; delta: string }
+	| { type: "tool_start"; id: string; tool: string; preview?: string }
+	| { type: "tool_end"; id: string; tool: string; ok: boolean };

package/src/core/events.ts

@@ -50,6 +50,7 @@ export class EventBus {
 	readonly sink: EventSink = {
 		turnStarted: (turn) => void this.deliver("turnStarted", turn),
 		turnEnded: (turn) => void this.deliver("turnEnded", turn),
+		turnProgress: (event) => void this.deliver("turnProgress", event),
 		changed: () => void this.deliver("changed"),
 	};
 }

package/src/core/host.ts

@@ -7,6 +7,7 @@ import { MigrationError, NotLinkedError, PluginError } from "./errors.ts";
 import { EventBus } from "./events.ts";
 import { HttpListeners, type ListenerConfig } from "./http/listeners.ts";
 import { type Locale, setLocale } from "./i18n/index.ts";
+import { contactsOf } from "./identity/identity-view.ts";
 import type { JudgeModel } from "./judging/model-judge.ts";
 import type { Logger } from "./log.ts";
 import type {
@@ -32,7 +33,7 @@ import {
 	conversationTurns,
 } from "./routing/conversation-turns.ts";
 import { surfacePort } from "./routing/surface-port.ts";
-import { AGENTS } from "./services.ts";
+import { CONVERSATIONS, IDENTITY, RUNTIME } from "./services.ts";
 import { setTimeZone } from "./time.ts";
 import { type ToolTierTable, toolTiers } from "./tool-tiers.ts";
 
@@ -154,6 +155,7 @@ export class Roundtable {
 	#listeners: HttpListeners | undefined;
 	#pool: SQL | undefined;
 	readonly #queue = new ChannelQueue();
+	readonly #warned = new Set<string>();
 	readonly #tiers: ToolTierTable;
 	readonly #events: EventBus;
 	#services: ServiceRegistry | undefined;
@@ -191,26 +193,40 @@ export class Roundtable {
 		return {
 			handle: (message) => router().handle(message),
 			background: (turn) => router().background(turn),
+			runsAs: (turn) => router().runsAs(turn),
 			target: (name) => router().target(name),
 			startFresh: (channel) => router().startFresh(channel),
 			deleteConversation: (channel) => router().deleteConversation(channel),
 			stop: (channel) => router().stop(channel),
 			postsInPlace: (channel) => router().postsInPlace(channel),
+			owns: (channel) => router().owns(channel),
+			takesBackground: (channel) => router().takesBackground(channel),
+			takesSystemReports: (channel) => router().takesSystemReports(channel),
 		};
 	}
 
 	/** The contributed surfaces by channel prefix; every call before linking throws NotLinkedError. */
 	#surfaces(): SurfacePort {
-		return surfacePort(() => {
-			if (!this.#sessions)
-				throw new NotLinkedError(
-					"chat surfaces are linked once every plugin is set up. Use surfaces from a service's start or from a handler, not during setup.",
-				);
-			return this.#registry.surfaces;
-		});
+		return surfacePort(
+			() => {
+				if (!this.#sessions)
+					throw new NotLinkedError(
+						"chat surfaces are linked once every plugin is set up. Use surfaces from a service's start or from a handler, not during setup.",
+					);
+				return this.#registry.surfaces;
+			},
+			{ deprecated: (message) => this.#deprecated(message) },
+		);
 	}
 
-	/** Turns over the agent server's runtime and the surfaces; every call before linking is refused with NotLinkedError. */
+	/** Logs a deprecation once per host. */
+	#deprecated(message: string): void {
+		if (this.#warned.has(message)) return;
+		this.#warned.add(message);
+		this.#options.logger.warn(message);
+	}
+
+	/** Turns over the runtime plugin's runtime and the surfaces; every call before linking is refused with NotLinkedError. */
 	#turns(): ConversationTurns {
 		return conversationTurns({
 			linked: () => {
@@ -222,8 +238,9 @@ export class Roundtable {
 			runtime: () => {
 				if (!this.#services)
 					throw new NotLinkedError("the host has not started yet.");
-				return this.#services.get(AGENTS).runtime;
+				return this.#services.get(RUNTIME);
 			},
+			registry: () => this.#services?.find(CONVERSATIONS),
 			surfaces: this.#surfaces(),
 			events: this.#events.sink,
 			selection: () => {
@@ -325,11 +342,16 @@ export class Roundtable {
 		const { routes, channels } = this.#registry;
 		this.#sessions = linkSessions(this.#registry);
 		this.#events.link(this.#registry.handlers);
+		const identity = this.#services.find(IDENTITY);
 		this.#router = new ChannelRouter({
 			claims: channels,
+			...(identity
+				? { contacts: contactsOf(identity), principals: identity }
+				: {}),
 			targets: (name) =>
 				this.#registry.backgroundTargets.find((t) => t.name === name),
 			queue: this.#queue,
+			surfaces: this.#surfaces(),
 			logger,
 			...(this.#options.conversations?.forwardJoinMs === undefined
 				? {}

package/src/core/http/listeners.ts

@@ -1,8 +1,16 @@
 import { chmodSync } from "node:fs";
-import type { Server } from "bun";
+import type { Server, WebSocketHandler } from "bun";
 import { PluginError } from "../errors.ts";
 import type { Logger } from "../log.ts";
 import { serveUnix } from "../shared/unix-server.ts";
+import {
+	type Connection,
+	DEFAULT_MAX_BUFFERED_BYTES,
+	DEFAULT_MAX_MESSAGE_BYTES,
+	isUpgrade,
+	SocketSet,
+	type WebSocketRoute,
+} from "./websocket.ts";
 
 /** A handler a plugin attaches to one of the host's configured listeners. */
 export interface HttpRoute {
@@ -13,6 +21,11 @@ export interface HttpRoute {
 	/** Omitted: every method, for a handler that answers the rest itself. */
 	methods?: readonly string[];
 	handle(request: Request): Response | Promise<Response>;
+	/**
+	 * Takes the route's WebSocket upgrade requests (GET with `Upgrade: websocket`); every other
+	 * request still reaches `handle`.
+	 */
+	websocket?: WebSocketRoute;
 }
 
 /** Where a listener serves: a unix socket, reached from outside through a tunnel, or a TCP port. */
@@ -44,6 +57,37 @@ function overlaps(a: HttpRoute, b: HttpRoute): boolean {
 	return matches(a, pathOf(b)) || matches(b, pathOf(a));
 }
 
+/** A non-special scheme's origin, such as `chrome-extension://<id>`, which URL reports as "null". */
+const OPAQUE_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/?#@:\s]+(?::\d+)?$/;
+
+/**
+ * Whether `origin` is `scheme://host[:port]` exactly as a browser sends it: a special scheme's
+ * origin, or a non-special one in lowercase without path, query, fragment, or user.
+ */
+const isOrigin = (origin: string) => {
+	const url = URL.parse(origin);
+	if (!url) return false;
+	return url.origin === "null"
+		? OPAQUE_ORIGIN.test(origin)
+		: url.origin === origin;
+};
+
+/** Refuses a WebSocket limit that is not a positive integer, naming the route and field. */
+function validateLimits(name: string, websocket: WebSocketRoute): void {
+	const limits: [string, number | undefined][] = [
+		["maxMessageBytes", websocket.maxMessageBytes],
+		["maxBufferedBytes", websocket.maxBufferedBytes],
+		["maxConnections", websocket.maxConnections],
+		["rate.messages", websocket.rate?.messages],
+		["rate.perMs", websocket.rate?.perMs],
+	];
+	for (const [field, value] of limits)
+		if (value !== undefined && !(Number.isSafeInteger(value) && value > 0))
+			throw new PluginError(
+				`route ${name} sets websocket ${field} to ${value}, which is not a positive integer`,
+			);
+}
+
 /** Refuses routes on unknown listeners, reused names, and any request two routes could both take. */
 function validate(
 	listeners: readonly ListenerConfig[],
@@ -53,6 +97,18 @@ function validate(
 	if (ids.size !== listeners.length)
 		throw new PluginError("a listener is configured twice");
 	routes.forEach((route, index) => {
+		if (route.websocket && route.methods && !route.methods.includes("GET"))
+			throw new PluginError(
+				`route ${route.name} takes WebSockets, so its methods must include GET`,
+			);
+		if (route.websocket) validateLimits(route.name, route.websocket);
+		const { origins } = route.websocket ?? {};
+		if (origins && origins !== "any")
+			for (const origin of origins)
+				if (!isOrigin(origin))
+					throw new PluginError(
+						`route ${route.name} lists origin ${JSON.stringify(origin)}, which is not a scheme://host[:port] origin`,
+					);
 		if (!ids.has(route.listener))
 			throw new PluginError(
 				`route ${route.name} needs listener ${route.listener}, which is not configured`,
@@ -71,6 +127,16 @@ function validate(
 const serverError = () =>
 	new Response("Internal Server Error", { status: 500 });
 
+/** The route that takes a request, when one does. */
+const routeFor = (routes: readonly HttpRoute[], request: Request) => {
+	// pi-lens-ignore: unchecked-throwing-call -- the server builds request.url, always an absolute URL
+	const path = new URL(request.url).pathname;
+	return routes.find(
+		(r) =>
+			matches(r, path) && (!r.methods || r.methods.includes(request.method)),
+	);
+};
+
 /**
  * Routes one listener's request; a request no route takes is 404, and a route that throws, or
  * whose promise rejects, is 500 with a fixed body. The failure is logged with the route's name
@@ -82,12 +148,7 @@ export async function routeRequest(
 	listener: string,
 	logger: Logger,
 ): 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)),
-	);
+	const route = routeFor(routes, request);
 	if (!route) return new Response("Not found", { status: 404 });
 	try {
 		return await route.handle(request);
@@ -97,39 +158,87 @@ export async function routeRequest(
 	}
 }
 
+/** What every request on one listener is served with. */
+interface ListenerContext {
+	listener: string;
+	logger: Logger;
+	sockets: SocketSet;
+}
+
+/**
+ * Routes one listener's request like `routeRequest`, except that a WebSocket upgrade for a route
+ * that takes them goes to its `websocket`; a failing `accept` answers and logs like a failing
+ * `handle`. Answers nothing once the socket is upgraded.
+ */
+async function serveRequest(
+	routes: readonly HttpRoute[],
+	request: Request,
+	server: Server<Connection>,
+	{ listener, logger, sockets }: ListenerContext,
+): Promise<Response | undefined> {
+	const route = routeFor(routes, request);
+	if (!route?.websocket || !isUpgrade(request))
+		return routeRequest(routes, request, listener, logger);
+	try {
+		return await sockets.upgrade(route.name, route.websocket, request, server);
+	} catch (err) {
+		logger.error({ err, route: route.name, listener }, "route failed");
+		return serverError();
+	}
+}
+
+type Fetch = (
+	request: Request,
+	server: Server<Connection>,
+) => Promise<Response | 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({
+	fetch: Fetch,
+	websocket: WebSocketHandler<Connection> | undefined,
+): Server<Connection> {
+	const options = {
 		port,
 		...(hostname ? { hostname } : {}),
 		idleTimeout: 0,
 		fetch,
 		error: serverError,
-	});
+		...(websocket ? { websocket } : {}),
+	};
+	// SAFETY: a listener without WebSocket routes passes no handler and never upgrades.
+	return Bun.serve(
+		options as Parameters<typeof Bun.serve<Connection>>[0],
+	) as Server<Connection>;
 }
 
+/** How long a stop waits for WebSocket routes' handlers to settle before it returns anyway. */
+const CLOSE_TIMEOUT_MS = 5_000;
+
 /** 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
+// pi-lens-ignore: large-class — four members: validation in the constructor, start, the WebSocket handler, and stop
 export class HttpListeners {
 	readonly #listeners: readonly ListenerConfig[];
 	readonly #routes: readonly HttpRoute[];
 	readonly #logger: Logger;
-	#servers: Server<undefined>[] = [];
+	readonly #sockets: SocketSet;
+	readonly #closeTimeoutMs: number;
+	#servers: Pick<Server<unknown>, "stop">[] = [];
 
-	/** Validates every route before any socket opens. */
+	/** Validates every route before any socket opens; `closeTimeoutMs` bounds how long a stop waits on WebSocket handlers. */
 	constructor(
 		listeners: readonly ListenerConfig[],
 		routes: readonly HttpRoute[],
 		logger: Logger,
+		options: { closeTimeoutMs?: number } = {},
 	) {
 		validate(listeners, routes);
 		this.#logger = logger;
 		this.#listeners = listeners;
 		this.#routes = routes;
+		this.#sockets = new SocketSet(logger);
+		this.#closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_TIMEOUT_MS;
 	}
 
 	/** Opens every listener; when one fails, the ones already open close again before the error is thrown. */
@@ -139,28 +248,72 @@ export class HttpListeners {
 				const routes = this.#routes.filter(
 					(route) => route.listener === listener.id,
 				);
-				const handle = (request: Request) =>
-					routeRequest(routes, request, listener.id, this.#logger);
+				const handle: Fetch = (request, server) =>
+					serveRequest(routes, request, server, {
+						listener: listener.id,
+						logger: this.#logger,
+						sockets: this.#sockets,
+					});
+				const websocket = this.#websocketHandler(listener.id, routes);
 				if ("socketPath" in listener) {
 					this.#servers.push(
-						serveUnix(listener.socketPath, handle, { error: serverError }),
+						websocket
+							? serveUnix(listener.socketPath, handle, {
+									error: serverError,
+									websocket,
+								})
+							: serveUnix(
+									listener.socketPath,
+									(request) =>
+										routeRequest(routes, request, listener.id, this.#logger),
+									{ error: serverError },
+								),
 					);
 					chmodSync(listener.socketPath, listener.mode ?? 0o660);
 				} else {
 					this.#servers.push(
-						serveTcp(listener.port, listener.hostname, handle),
+						serveTcp(listener.port, listener.hostname, handle, websocket),
 					);
 				}
 			}
 		} catch (error) {
-			this.stop();
+			void this.stop();
 			throw error;
 		}
 	}
 
-	/** Stops accepting at once and cuts open connections, such as event streams, without waiting on them. */
-	stop(): void {
+	/** The listener's WebSocket handler, sized for its largest route limits; none without WebSocket routes. */
+	#websocketHandler(
+		listener: string,
+		routes: readonly HttpRoute[],
+	): WebSocketHandler<Connection> | undefined {
+		const websockets = routes.flatMap((route) =>
+			route.websocket ? [route.websocket] : [],
+		);
+		if (websockets.length === 0) return undefined;
+		return this.#sockets.handler(listener, {
+			maxMessageBytes: Math.max(
+				...websockets.map(
+					(w) => w.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES,
+				),
+			),
+			maxBufferedBytes: Math.max(
+				...websockets.map(
+					(w) => w.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES,
+				),
+			),
+		});
+	}
+
+	/**
+	 * Stops accepting at once and cuts open connections, such as event streams, without waiting on
+	 * them. Open WebSockets get close code 1001 first, and the stop resolves once their routes'
+	 * handlers have settled, or after the close timeout.
+	 */
+	async stop(): Promise<void> {
+		this.#sockets.closeAll();
 		for (const server of this.#servers) void server.stop(true);
 		this.#servers = [];
+		await this.#sockets.drain(this.#closeTimeoutMs);
 	}
 }