pi-roundtable 0.1.0 → 0.2.1

package/src/core/registry/contributions.ts

@@ -1,6 +1,6 @@
 import type { AgentSeed } from "../agents/agent-store.ts";
-import type { ChannelClaim } from "../contract/channels.ts";
-import type { InteractionContribution } from "../contract/discord.ts";
+import type { BackgroundTarget, ChannelClaim } from "../contract/channels.ts";
+import type { ChatSurface } from "../contract/surface.ts";
 import type { ToolContribution } from "../define.ts";
 import { PluginError } from "../errors.ts";
 import { type HoldRule, holdChain } from "../holds.ts";
@@ -10,9 +10,14 @@ import {
 	type Contribution,
 	type EventHandlers,
 	type LinkedSessions,
+	type Persona,
 	type PluginContext,
 	type PromptSection,
+	pluginContext,
 	type RoundtablePlugin,
+	refuseRemovedEvents,
+	refuseRemovedParts,
+	refuseRemovedSurfaceMethods,
 	type Service,
 } from "../plugin.ts";
 import {
@@ -20,39 +25,51 @@ import {
 	type SessionTool,
 	type ToolSelection,
 } from "../sessions.ts";
+import { TIERS } from "../speakers.ts";
 import type { ToolTierTable } from "../tool-tiers.ts";
+import { ServiceRegistry } from "./services.ts";
 
 /** Everything the plugins contributed, in contribution order. */
 export interface Registry {
 	services: Service[];
+	/** The plugin that contributed each service. */
+	servicePlugins: Map<Service, string>;
 	handlers: { plugin: string; events: EventHandlers }[];
-	interactions: InteractionContribution[];
 	routes: HttpRoute[];
 	holdRules: HoldRule[];
 	piPackages: string[];
 	sessionTools: SessionTool[];
 	channels: ChannelClaim[];
+	/** The contributed chat surfaces, each also in `services` as `surface:<prefix>`. */
+	surfaces: ChatSurface[];
+	personas: Persona[];
+	backgroundTargets: BackgroundTarget[];
 	dashboard: string[];
 	tools: ToolContribution[];
 	seeds: AgentSeed[];
 	prompt: PromptSection[];
 	agentSelections: (() => ToolSelection)[];
+	requiredTools: string[];
 }
 
 export const emptyRegistry = (): Registry => ({
 	services: [],
+	servicePlugins: new Map(),
 	handlers: [],
-	interactions: [],
 	routes: [],
 	holdRules: [],
 	piPackages: [],
 	sessionTools: [],
 	channels: [],
+	surfaces: [],
+	personas: [],
+	backgroundTargets: [],
 	dashboard: [],
 	tools: [],
 	seeds: [],
 	prompt: [],
 	agentSelections: [],
+	requiredTools: [],
 });
 
 /** The edit distance between two words, for naming the key a typo meant. */
@@ -129,6 +146,99 @@ class Names {
 	}
 }
 
+/** The kind of a conversation the agent server runs itself, which no plugin's persona may take. */
+const RESERVED_KIND = "agent";
+
+/**
+ * Refuses a persona without a kind, for the reserved agent kind, or for a kind another plugin's
+ * persona already has, so a conversation's prompt is never a matter of plugin order.
+ */
+function claimPersona(
+	kinds: Map<string, string>,
+	plugin: string,
+	persona: Persona,
+): void {
+	const { kind } = persona;
+	if (typeof kind !== "string" || kind === "")
+		throw new PluginError(
+			`plugin ${plugin}: a persona needs a kind, a non-empty string such as "study", and got ${JSON.stringify(kind)}.`,
+		);
+	if (kind === RESERVED_KIND)
+		throw new PluginError(
+			`plugin ${plugin}: the persona kind "${RESERVED_KIND}" is reserved for the agent server's agents. Give the persona the kind of your own conversations.`,
+		);
+	if (typeof persona.prompt !== "function")
+		throw new PluginError(
+			`plugin ${plugin}: the persona of kind "${kind}" needs a prompt() that returns its text.`,
+		);
+	const other = kinds.get(kind);
+	if (other !== undefined)
+		throw new PluginError(
+			`plugin ${plugin}: persona kind "${kind}" is already registered by plugin ${other}. Keep one persona per kind.`,
+		);
+	kinds.set(kind, plugin);
+}
+
+/**
+ * Refuses a background target without a name or a label, or whose name another plugin's target
+ * already has, so a stored schedule's target never depends on plugin order.
+ */
+function claimTarget(
+	names: Map<string, string>,
+	plugin: string,
+	target: BackgroundTarget,
+): void {
+	const { name } = target;
+	if (typeof name !== "string" || name === "")
+		throw new PluginError(
+			`plugin ${plugin}: a background target needs a name, a non-empty string such as "support", and got ${JSON.stringify(name)}.`,
+		);
+	if (typeof target.label !== "function")
+		throw new PluginError(
+			`plugin ${plugin}: the background target "${name}" needs a label(locale) that returns its name for lists.`,
+		);
+	const other = names.get(name);
+	if (other !== undefined)
+		throw new PluginError(
+			`plugin ${plugin}: background target "${name}" is already registered by plugin ${other}. Keep one target per name.`,
+		);
+	names.set(name, plugin);
+}
+
+/** The surface's own words for what a prefix must be, checked before its service is named. */
+function checkSurfacePrefix(plugin: string, prefix: unknown): void {
+	if (typeof prefix !== "string" || prefix === "" || /[:\s]/.test(prefix))
+		throw new PluginError(
+			`plugin ${plugin}: a surface is named by the prefix of its channel keys, a non-empty word without a colon or space, such as discord; got ${JSON.stringify(prefix)}.`,
+		);
+}
+
+/**
+ * The surface as a service: it starts with the router's `handle` as its delivery, which drops
+ * and logs a message that belongs to another prefix, and stops with the surface.
+ */
+function surfaceService(
+	surface: ChatSurface,
+	context: Pick<PluginContext, "logger" | "conversations">,
+): Service {
+	const { logger, conversations } = context;
+	return {
+		name: `surface:${surface.surface}`,
+		start: () =>
+			surface.start((message) => {
+				if (!message.channel.startsWith(`${surface.surface}:`)) {
+					logger.error(
+						{ surface: surface.surface, channel: message.channel },
+						"a surface delivered a message of another prefix; dropped",
+					);
+					return;
+				}
+				void conversations.handle(message);
+			}),
+		...(surface.stop ? { stop: () => surface.stop?.() } : {}),
+	};
+}
+
 /**
  * Sets up every plugin in order and collects what each adds. A plugin that adds nothing, that
  * reuses a name, or whose setup throws or returns a part the contract does not have is refused
@@ -136,17 +246,25 @@ class Names {
  */
 export async function collectContributions(
 	plugins: readonly RoundtablePlugin[],
-	context: PluginContext,
+	context: Omit<PluginContext, "services">,
 	tiers: ToolTierTable,
+	services: ServiceRegistry = new ServiceRegistry(plugins),
 ): Promise<Registry> {
 	const registry = emptyRegistry();
-	const services = new Names("service");
+	const serviceNames = new Names("service");
 	const sessionTools = new Names("session tool");
 	const holds = new Names("hold rule");
+	const surfaces = new Names("surface");
+	const personaKinds = new Map<string, string>();
+	const targetNames = new Map<string, string>();
 	for (const plugin of plugins) {
 		let contribution: Contribution;
 		try {
-			contribution = await plugin.setup(context);
+			contribution = await services.setUp(plugin, () =>
+				plugin.setup(
+					pluginContext(plugin, context, services.forPlugin(plugin)),
+				),
+			);
 		} catch (error) {
 			if (error instanceof PluginError) throw error;
 			// Some messages end in a period already, such as a NotLinkedError's.
@@ -162,53 +280,87 @@ export async function collectContributions(
 			throw new PluginError(
 				`plugin ${plugin.name}: setup must return an object of the parts it adds; return {} to add none.`,
 			);
+		refuseRemovedParts(plugin.name, contribution);
 		checkKeys(plugin.name, contribution);
+		if (contribution.events)
+			refuseRemovedEvents(plugin.name, contribution.events);
 		const {
 			events,
-			interactions = [],
 			http = [],
 			holdRules = [],
 			piPackages = [],
 			channels = [],
+			surfaces: contributedSurfaces = [],
+			personas = [],
+			backgroundTargets = [],
 			dashboard = [],
 			tools = [],
 			seeds = [],
 			prompt = [],
+			requiredTools = [],
 		} = contribution;
 		const parts = [
 			contribution.services ?? [],
-			interactions,
 			http,
 			holdRules,
 			piPackages,
 			contribution.sessionTools ?? [],
 			channels,
+			contributedSurfaces,
+			personas,
+			backgroundTargets,
 			dashboard,
 			tools,
 			seeds,
 			prompt,
+			requiredTools,
 			contribution.agentSelection ? [contribution.agentSelection] : [],
+			Object.keys(contribution.toolTiers ?? {}),
 		];
 		const declares =
 			(plugin.migrations?.length ?? 0) > 0 ||
+			(plugin.provides?.length ?? 0) > 0 ||
 			Object.keys(plugin.providers ?? {}).length > 0 ||
 			plugin.preflight !== undefined ||
-			plugin.useCommands !== undefined ||
-			plugin.agentServer !== undefined ||
-			plugin.stopTurn !== undefined;
+			// It works through a service it read, such as the Discord plugin's command registrar.
+			services.reads(plugin);
 		if (!declares && !events && parts.every((part) => part.length === 0))
 			throw new PluginError(
 				`plugin ${plugin.name} adds nothing. Give it a part (tools, services, channels, and so on), a migration, or a provider, or remove it.`,
 			);
+		// Its surfaces start before its own services, which may rely on the connection.
+		for (const surface of contributedSurfaces) {
+			refuseRemovedSurfaceMethods(plugin.name, surface);
+			checkSurfacePrefix(plugin.name, surface.surface);
+			surfaces.claim(plugin.name, surface.surface);
+			const service = surfaceService(surface, context);
+			serviceNames.claim(plugin.name, service.name);
+			registry.surfaces.push(surface);
+			registry.services.push(service);
+			registry.servicePlugins.set(service, plugin.name);
+		}
 		for (const service of contribution.services ?? []) {
-			services.claim(plugin.name, service.name);
+			serviceNames.claim(plugin.name, service.name);
 			registry.services.push(service);
+			registry.servicePlugins.set(service, plugin.name);
 		}
+		for (const persona of personas)
+			claimPersona(personaKinds, plugin.name, persona);
+		for (const target of backgroundTargets)
+			claimTarget(targetNames, plugin.name, target);
 		for (const rule of holdRules) holds.claim(plugin.name, rule.name);
 		for (const tool of contribution.sessionTools ?? []) {
 			sessionTools.claim(plugin.name, tool.name);
 			registry.sessionTools.push(tool);
 		}
+		if (contribution.toolTiers) {
+			for (const [tool, tier] of Object.entries(contribution.toolTiers))
+				if (!(TIERS as readonly string[]).includes(tier))
+					throw new PluginError(
+						`plugin ${plugin.name}: toolTiers names tool ${tool} at tier ${JSON.stringify(tier)}; use one of ${TIERS.join(", ")}.`,
+					);
+			tiers.declare(plugin.name, contribution.toolTiers);
+		}
 		for (const tool of tools) {
 			tiers.declare(plugin.name, { [tool.name]: tool.minTier });
 			sessionTools.claim(plugin.name, tool.session.name);
@@ -222,20 +374,25 @@ export async function collectContributions(
 		if (contribution.agentSelection)
 			registry.agentSelections.push(contribution.agentSelection);
 		if (events) registry.handlers.push({ plugin: plugin.name, events });
-		registry.interactions.push(...interactions);
 		registry.routes.push(...http);
 		registry.holdRules.push(...holdRules);
 		registry.piPackages.push(...piPackages);
 		registry.channels.push(...channels);
+		registry.personas.push(...personas);
+		registry.backgroundTargets.push(...backgroundTargets);
 		registry.dashboard.push(...dashboard);
 		registry.seeds.push(...seeds);
 		registry.prompt.push(...prompt);
+		registry.requiredTools.push(...requiredTools);
 	}
 	return registry;
 }
 
 /** Links the collected session parts; throws PluginError on a clash. */
 export function linkSessions(registry: Registry): LinkedSessions {
+	const personas = new Map(
+		registry.personas.map((persona) => [persona.kind, persona] as const),
+	);
 	return {
 		holds: holdChain(registry.holdRules),
 		// A package two plugins ask for loads once, where it was first asked for.
@@ -243,6 +400,8 @@ export function linkSessions(registry: Registry): LinkedSessions {
 		plan: compileSessionPlan(registry.sessionTools),
 		seeds: registry.seeds,
 		prompt: registry.prompt,
+		persona: (kind) => personas.get(kind)?.prompt(),
+		requiredTools: [...new Set(registry.requiredTools)],
 		agentTools: registry.tools.filter((t) => t.agent).map((t) => t.name),
 		agentSelection: () => mergeSelections(registry.agentSelections),
 	};

package/src/core/registry/providers.ts

@@ -1,11 +1,17 @@
-import type { Judge, Providers } from "../contract/providers.ts";
+import type {
+	Judge,
+	Providers,
+	ResolvedProviders,
+} from "../contract/providers.ts";
 import { PluginError, ProviderError } from "../errors.ts";
 import { type JudgeModel, ModelJudge } from "../judging/model-judge.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
+import { nearest } from "./contributions.ts";
 
 const SLOTS = [
 	"judge",
 	"images",
+	"runtime",
 ] as const satisfies readonly (keyof Providers)[];
 
 /** A judge with no model: every question throws, so each caller keeps its own default. */
@@ -24,20 +30,39 @@ function defaults(judgeModel: JudgeModel | undefined): Providers {
 		judge: judgeModel ? new ModelJudge(judgeModel) : unconfiguredJudge(),
 		images: async () => {
 			throw new ProviderError(
-				"no image provider is configured; agents keep the neutral avatar",
+				"no image provider is configured; agents use generated avatars",
+			);
+		},
+		runtime: () => {
+			throw new ProviderError(
+				"no runtime provider is configured: the agent server builds the Pi runtime when no plugin fills the runtime slot",
 			);
 		},
 	};
 }
 
+/** Refuses a provider slot the contract does not have, naming the nearest one and the valid ones. */
+function checkSlots(plugin: RoundtablePlugin): void {
+	for (const slot of Object.keys(plugin.providers ?? {})) {
+		if ((SLOTS as readonly string[]).includes(slot)) continue;
+		const meant = nearest(slot, SLOTS);
+		throw new PluginError(
+			`plugin ${plugin.name}: unknown provider slot "${slot}".${
+				meant ? ` Did you mean "${meant}"?` : ""
+			} The slots are ${SLOTS.join(", ")}.`,
+		);
+	}
+}
+
 /** Each slot from the one plugin that fills it, else the core's default; two plugins filling one slot clash. */
 export function resolveProviders(
 	plugins: readonly RoundtablePlugin[],
 	judgeModel?: JudgeModel,
-): Providers {
-	const resolved = defaults(judgeModel);
+): ResolvedProviders {
+	const resolved: Providers = defaults(judgeModel);
 	const filledBy = new Map<keyof Providers, string>();
 	for (const plugin of plugins) {
+		checkSlots(plugin);
 		for (const slot of SLOTS) {
 			const provided = plugin.providers?.[slot];
 			if (!provided) continue;
@@ -51,5 +76,10 @@ export function resolveProviders(
 			Object.assign(resolved, { [slot]: provided });
 		}
 	}
-	return resolved;
+	return { ...resolved, filled: new Set(filledBy.keys()) };
+}
+
+/** Whether a plugin fills the `images` slot, so agents can be offered drawing before any host runs. */
+export function fillsImages(plugins: readonly RoundtablePlugin[]): boolean {
+	return plugins.some((plugin) => Boolean(plugin.providers?.images));
 }

package/src/core/registry/services.ts

@@ -0,0 +1,229 @@
+import type { ServiceKey, Services } from "../contract/services.ts";
+import { PluginError } from "../errors.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+
+/** The host's words for reading a service no plugin declares; `testPlugin` says how to give one instead. */
+const HOST_ADVICE =
+	"Register a plugin that provides it, before the plugin that reads it.";
+
+/** The services a plugin declares, checked before any setup: each a key with an id, once per plugin. */
+function declaredBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
+	const { provides } = plugin;
+	if (provides === undefined) return [];
+	if (!Array.isArray(provides))
+		throw new PluginError(
+			`plugin ${plugin.name}: provides must be a list of service keys made with serviceKey().`,
+		);
+	const seen = new Set<string>();
+	for (const key of provides) {
+		if (typeof key?.id !== "string" || key.id === "")
+			throw new PluginError(
+				`plugin ${plugin.name}: provides has an entry that is not a service key; make each with serviceKey("<id>").`,
+			);
+		if (seen.has(key.id))
+			throw new PluginError(
+				`plugin ${plugin.name}: provides lists service ${key.id} twice.`,
+			);
+		seen.add(key.id);
+	}
+	return provides;
+}
+
+/** The services a plugin replaces, checked to be a list of keys; empty when it replaces none. */
+function replacedBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
+	const { replaces } = plugin;
+	if (replaces === undefined) return [];
+	if (!Array.isArray(replaces))
+		throw new PluginError(
+			`plugin ${plugin.name}: replaces must be a list of service keys made with serviceKey().`,
+		);
+	for (const key of replaces)
+		if (typeof key?.id !== "string" || key.id === "")
+			throw new PluginError(
+				`plugin ${plugin.name}: replaces has an entry that is not a service key; make each with serviceKey("<id>").`,
+			);
+	return replaces;
+}
+
+/**
+ * Applies every plugin's `replaces`: the plugin that provides a replaced service is dropped and
+ * the replacement is set up where it stood. Refuses a key nobody provides, a key two plugins
+ * replace, a replacement that does not declare what it replaces, and a partial replacement, where
+ * the dropped plugin provides a service the replacement does not.
+ */
+export function replaceServices(
+	plugins: readonly RoundtablePlugin[],
+): RoundtablePlugin[] {
+	const replacers = plugins.filter((plugin) => replacedBy(plugin).length > 0);
+	if (replacers.length === 0) return [...plugins];
+	// Only a plugin that does not replace can be the one replaced.
+	const providerOf = new Map<string, RoundtablePlugin>();
+	for (const plugin of plugins)
+		if (!replacers.includes(plugin))
+			for (const key of declaredBy(plugin))
+				if (!providerOf.has(key.id)) providerOf.set(key.id, plugin);
+	const claimed = new Map<string, RoundtablePlugin>();
+	const dropped = new Map<RoundtablePlugin, RoundtablePlugin>();
+	for (const plugin of replacers) {
+		const own = new Set(declaredBy(plugin).map((key) => key.id));
+		for (const key of replacedBy(plugin)) {
+			const other = claimed.get(key.id);
+			if (other)
+				throw new PluginError(
+					`plugin ${plugin.name}: service ${key.id} is also replaced by plugin ${other.name}. Keep one replacement per service.`,
+				);
+			claimed.set(key.id, plugin);
+			if (!own.has(key.id))
+				throw new PluginError(
+					`plugin ${plugin.name}: replaces service ${key.id} but does not list it in provides. Provide what you replace.`,
+				);
+			const provider = providerOf.get(key.id);
+			if (!provider)
+				throw new PluginError(
+					`plugin ${plugin.name}: replaces service ${key.id}, which no other registered plugin provides. Remove it from replaces, or register the plugin that provides it.`,
+				);
+			dropped.set(provider, plugin);
+		}
+	}
+	for (const [provider, replacement] of dropped) {
+		const replaced = new Set(replacedBy(replacement).map((key) => key.id));
+		const missing = declaredBy(provider).filter((key) => !replaced.has(key.id));
+		if (missing.length > 0)
+			throw new PluginError(
+				`plugin ${replacement.name}: replacing plugin ${provider.name} would drop ${missing.map((key) => key.id).join(", ")} too, which it also provides. Replace every service of ${provider.name}, or none.`,
+			);
+	}
+	// The replacement takes the place of the first plugin it drops, not the place it was listed in.
+	const result: RoundtablePlugin[] = [];
+	for (const plugin of plugins) {
+		if (replacers.includes(plugin)) continue;
+		const replacement = dropped.get(plugin);
+		if (!replacement) result.push(plugin);
+		else if (!result.includes(replacement)) result.push(replacement);
+	}
+	return result;
+}
+
+/** What to do about a service whose provider has not set up yet: the order the plugins are registered in. */
+function orderHint(
+	provider: RoundtablePlugin,
+	reader: RoundtablePlugin | undefined,
+): string {
+	if (reader === undefined) return "";
+	if (reader === provider)
+		return ` Plugin ${provider.name} reads it before its own setup has provided it.`;
+	return ` Register plugin ${provider.name} before plugin ${reader.name}.`;
+}
+
+/**
+ * The services the plugins provide and read. It knows from `provides` which plugin declares each
+ * key before any setup, so a read can tell a service switched off from one that is not set up yet.
+ */
+export class ServiceRegistry {
+	readonly #declaredBy = new Map<string, RoundtablePlugin>();
+	readonly #values = new Map<string, unknown>();
+	readonly #advice: string;
+	/** The plugin whose setup is running, the only one that may provide. */
+	#setting: RoundtablePlugin | undefined;
+	/** The plugins that have read a service, such as one that adds its commands through it. */
+	readonly #readers = new Set<RoundtablePlugin>();
+
+	/** `advice` says how to get a service no plugin declares; the host's is to register one that does. */
+	constructor(plugins: readonly RoundtablePlugin[], advice = HOST_ADVICE) {
+		this.#advice = advice;
+		for (const plugin of plugins)
+			for (const key of declaredBy(plugin)) {
+				const other = this.#declaredBy.get(key.id);
+				if (other)
+					throw new PluginError(
+						`plugin ${plugin.name}: service ${key.id} is also provided by plugin ${other.name}. Keep one provider, or have one plugin replace the other with replaces.`,
+					);
+				this.#declaredBy.set(key.id, plugin);
+			}
+	}
+
+	/** Provides a service the host or a test holds itself, without a plugin's setup. */
+	preset<T>(key: ServiceKey<T>, value: T): void {
+		this.#values.set(key.id, value);
+	}
+
+	/** The service, for the host's own reads; throws like a plugin's `get`. */
+	get<T>(key: ServiceKey<T>): T {
+		return this.#read(key, undefined, true) as T;
+	}
+
+	find<T>(key: ServiceKey<T>): T | undefined {
+		return this.#read(key, undefined, false);
+	}
+
+	#read<T>(
+		key: ServiceKey<T>,
+		reader: RoundtablePlugin | undefined,
+		required: boolean,
+	): T | undefined {
+		if (this.#values.has(key.id)) return this.#values.get(key.id) as T;
+		const provider = this.#declaredBy.get(key.id);
+		if (provider) {
+			throw new PluginError(
+				`service ${key.id} is not provided yet; plugin ${provider.name} provides it.${orderHint(provider, reader)}`,
+			);
+		}
+		if (!required) return undefined;
+		throw new PluginError(
+			`service ${key.id} is not provided. ${key.absent ?? this.#advice}`,
+		);
+	}
+
+	/** The view one plugin's setup gets: its reads name it, and only it may provide what it declares. */
+	forPlugin(plugin: RoundtablePlugin): Services {
+		return {
+			get: <T>(key: ServiceKey<T>) => {
+				this.#readers.add(plugin);
+				return this.#read(key, plugin, true) as T;
+			},
+			find: <T>(key: ServiceKey<T>) => {
+				this.#readers.add(plugin);
+				return this.#read(key, plugin, false);
+			},
+			provide: (key, value) => {
+				if (this.#setting !== plugin)
+					throw new PluginError(
+						`plugin ${plugin.name}: services are provided from setup only; provide ${key.id} while setup runs.`,
+					);
+				if (this.#declaredBy.get(key.id) !== plugin)
+					throw new PluginError(
+						`plugin ${plugin.name}: cannot provide service ${key.id}, which it does not declare. Add it to the plugin's provides.`,
+					);
+				if (this.#values.has(key.id))
+					throw new PluginError(
+						`plugin ${plugin.name}: service ${key.id} is provided twice.`,
+					);
+				this.#values.set(key.id, value);
+			},
+		};
+	}
+
+	/** Whether the plugin read a service: it then works through that service, even when it returns no part. */
+	reads(plugin: RoundtablePlugin): boolean {
+		return this.#readers.has(plugin);
+	}
+
+	/** Runs a plugin's setup with `provide` open to it, and refuses it when it declared a service it did not provide. */
+	async setUp<T>(
+		plugin: RoundtablePlugin,
+		setup: () => Promise<T> | T,
+	): Promise<T> {
+		this.#setting = plugin;
+		try {
+			const result = await setup();
+			for (const key of declaredBy(plugin))
+				if (!this.#values.has(key.id))
+					throw new PluginError(
+						`plugin ${plugin.name}: declares that it provides service ${key.id}, but setup did not provide it. Call services.provide(...) in setup, or remove it from provides.`,
+					);
+			return result;
+		} finally {
+			this.#setting = undefined;
+		}
+	}
+}

package/src/core/routing/channel-queue.ts

@@ -42,3 +42,8 @@ export class ChannelQueue {
 		return [...this.#sizes.keys()];
 	}
 }
+
+/** A queue of its own, apart from the host's; for work that must not wait behind a running turn. */
+export function channelQueue(): ChannelQueue {
+	return new ChannelQueue();
+}