pi-roundtable 0.8.0 → 0.9.1

package/src/core/registry/contributions.ts

@@ -2,7 +2,7 @@ import type { AgentSeed } from "../agents/agent-store.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 { NotLinkedError, PluginError } from "../errors.ts";
 import { type HoldRule, holdChain } from "../holds.ts";
 import type { HttpRoute } from "../http/listeners.ts";
 import {
@@ -20,6 +20,10 @@ import {
 	refuseRemovedSurfaceMethods,
 	type Service,
 } from "../plugin.ts";
+import {
+	type DirectChannelProvider,
+	directChannelsPort,
+} from "../presence/direct-channels.ts";
 import {
 	compileSessionPlan,
 	type SessionTool,
@@ -44,6 +48,8 @@ export interface Registry {
 	surfaces: ChatSurface[];
 	personas: Persona[];
 	backgroundTargets: BackgroundTarget[];
+	/** The contributed direct channels, in contribution order. */
+	directChannels: DirectChannelProvider[];
 	dashboard: string[];
 	tools: ToolContribution[];
 	seeds: AgentSeed[];
@@ -64,6 +70,7 @@ export const emptyRegistry = (): Registry => ({
 	surfaces: [],
 	personas: [],
 	backgroundTargets: [],
+	directChannels: [],
 	dashboard: [],
 	tools: [],
 	seeds: [],
@@ -171,6 +178,14 @@ function claimPersona(
 		throw new PluginError(
 			`plugin ${plugin}: the persona of kind "${kind}" needs a prompt() that returns its text.`,
 		);
+	if (
+		persona.memory !== undefined &&
+		persona.memory !== "speaker" &&
+		persona.memory !== "none"
+	)
+		throw new PluginError(
+			`plugin ${plugin}: the persona of kind "${kind}" has memory ${JSON.stringify(persona.memory)}; expected "speaker" or "none".`,
+		);
 	const other = kinds.get(kind);
 	if (other !== undefined)
 		throw new PluginError(
@@ -179,6 +194,31 @@ function claimPersona(
 	kinds.set(kind, plugin);
 }
 
+/**
+ * Refuses a direct channel without a name, a label, or `reaches`, or whose name another plugin's
+ * already has, so the providers a person is reached through never depend on a typo.
+ */
+function claimDirectChannel(
+	names: Names,
+	plugin: string,
+	provider: DirectChannelProvider,
+): void {
+	const { name } = provider;
+	if (typeof name !== "string" || name === "")
+		throw new PluginError(
+			`plugin ${plugin}: a direct channel needs a name, a non-empty string such as "discord", and got ${JSON.stringify(name)}.`,
+		);
+	if (typeof provider.label !== "string" || provider.label === "")
+		throw new PluginError(
+			`plugin ${plugin}: the direct channel "${name}" needs a label, such as "a direct message on Discord", which the notify tool names it by.`,
+		);
+	if (typeof provider.reaches !== "function")
+		throw new PluginError(
+			`plugin ${plugin}: the direct channel "${name}" needs reaches(principalId), which finds a person's own conversation there.`,
+		);
+	names.claim(plugin, name);
+}
+
 /**
  * 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.
@@ -242,19 +282,32 @@ function surfaceService(
 /**
  * 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
- * with its name and what to fix.
+ * with its name and what to fix. The context's `directChannels` are the contributed ones, read
+ * once every plugin is set up.
  */
 export async function collectContributions(
 	plugins: readonly RoundtablePlugin[],
-	context: Omit<PluginContext, "services">,
+	base: Omit<PluginContext, "services" | "directChannels">,
 	tiers: ToolTierTable,
 	services: ServiceRegistry = new ServiceRegistry(plugins),
 ): Promise<Registry> {
 	const registry = emptyRegistry();
+	let collected = false;
+	const context: Omit<PluginContext, "services"> = {
+		...base,
+		directChannels: directChannelsPort(() => {
+			if (!collected)
+				throw new NotLinkedError(
+					"direct channels are linked once every plugin is set up. Use them from a service's start, a handler, or a session tool, not during setup.",
+				);
+			return registry.directChannels;
+		}, base.surfaces),
+	};
 	const serviceNames = new Names("service");
 	const sessionTools = new Names("session tool");
 	const holds = new Names("hold rule");
 	const surfaces = new Names("surface");
+	const directChannelNames = new Names("direct channel");
 	const personaKinds = new Map<string, string>();
 	const targetNames = new Map<string, string>();
 	for (const plugin of plugins) {
@@ -293,6 +346,7 @@ export async function collectContributions(
 			surfaces: contributedSurfaces = [],
 			personas = [],
 			backgroundTargets = [],
+			directChannels = [],
 			dashboard = [],
 			tools = [],
 			seeds = [],
@@ -309,6 +363,7 @@ export async function collectContributions(
 			contributedSurfaces,
 			personas,
 			backgroundTargets,
+			directChannels,
 			dashboard,
 			tools,
 			seeds,
@@ -348,6 +403,8 @@ export async function collectContributions(
 			claimPersona(personaKinds, plugin.name, persona);
 		for (const target of backgroundTargets)
 			claimTarget(targetNames, plugin.name, target);
+		for (const provider of directChannels)
+			claimDirectChannel(directChannelNames, plugin.name, provider);
 		for (const rule of holdRules) holds.claim(plugin.name, rule.name);
 		for (const tool of contribution.sessionTools ?? []) {
 			sessionTools.claim(plugin.name, tool.name);
@@ -380,12 +437,14 @@ export async function collectContributions(
 		registry.channels.push(...channels);
 		registry.personas.push(...personas);
 		registry.backgroundTargets.push(...backgroundTargets);
+		registry.directChannels.push(...directChannels);
 		registry.dashboard.push(...dashboard);
 		registry.seeds.push(...seeds);
 		registry.prompt.push(...prompt);
 		registry.requiredTools.push(...requiredTools);
 	}
 	services.settle();
+	collected = true;
 	return registry;
 }
 
@@ -402,6 +461,7 @@ export function linkSessions(registry: Registry): LinkedSessions {
 		seeds: registry.seeds,
 		prompt: registry.prompt,
 		persona: (kind) => personas.get(kind)?.prompt(),
+		personaMemory: (kind) => personas.get(kind)?.memory ?? "speaker",
 		requiredTools: [...new Set(registry.requiredTools)],
 		agentTools: registry.tools.flatMap((t) => (t.agent ? [t.name] : [])),
 		agentSelection: () => mergeSelections(registry.agentSelections),

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

@@ -1,3 +1,4 @@
+import { HostStoppingError } from "../errors.ts";
 import type { ChannelKey } from "../sessions.ts";
 
 /** Runs tasks one at a time per channel, in arrival order; different channels run independently. */
@@ -5,6 +6,7 @@ export class ChannelQueue {
 	readonly #tails = new Map<ChannelKey, Promise<unknown>>();
 	readonly #sizes = new Map<ChannelKey, number>();
 	readonly #listeners: ((channel: ChannelKey) => void)[] = [];
+	#closed = false;
 
 	/** Called whenever a channel's count of running and waiting tasks changes. */
 	onChange(listener: (channel: ChannelKey) => void): void {
@@ -15,11 +17,26 @@ export class ChannelQueue {
 		for (const listener of this.#listeners) listener(channel);
 	}
 
+	/** Whether the host is shutting down, so no task starts any more. */
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	/**
+	 * Starts the shutdown: from now on a task that has not started, whether queued before or after
+	 * this call, is refused with HostStoppingError. A running task finishes.
+	 */
+	close(): void {
+		this.#closed = true;
+	}
+
 	run<T>(channel: ChannelKey, task: () => Promise<T>): Promise<T> {
+		const start = () =>
+			this.#closed ? Promise.reject(new HostStoppingError()) : task();
 		this.#sizes.set(channel, this.size(channel) + 1);
 		this.#changed(channel);
 		const previous = this.#tails.get(channel) ?? Promise.resolve();
-		const result = previous.then(task, task);
+		const result = previous.then(start, start);
 		const tail = result.catch(() => undefined);
 		this.#tails.set(channel, tail);
 		void tail.then(() => {

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

@@ -1,4 +1,6 @@
 import {
+	type Admission,
+	type BackgroundRunsAs,
 	type BackgroundTarget,
 	type BackgroundTurn,
 	type ChannelClaim,
@@ -8,11 +10,22 @@ import {
 	type ScheduledOutcome,
 	STEERED_MARK,
 } from "../contract/channels.ts";
-import { PluginError } from "../errors.ts";
+import { parseChannelKey, type SurfacePort } from "../contract/surface.ts";
+import { IdentityError } from "../domain/errors.ts";
+import { HostStoppingError, PluginError } from "../errors.ts";
+import { messages } from "../i18n/index.ts";
+import type { ActorFacts } from "../identity/actor-facts.ts";
+import type { Contact, ContactAssessor } from "../identity/contact.ts";
+import {
+	type IdentityService,
+	systemSpeaker,
+} from "../identity/identity-service.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
 import type { Logger } from "../log.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { ChannelQueue } from "./channel-queue.ts";
 import { ForwardJoin } from "./forward-join.ts";
+import { isSystemTurn } from "./system-turns.ts";
 
 export interface ChannelRouterOptions {
 	/** Claims in registration order; the router orders them by priority. */
@@ -21,6 +34,15 @@ export interface ChannelRouterOptions {
 	/** The contributed background target of a name, read at use time. */
 	targets(name: string): BackgroundTarget | undefined;
 	logger: Logger;
+	/** Who the authors of messages are; without it, no message carries a speaker. */
+	contacts?: ContactAssessor;
+	/** Whom a background turn runs as; without it, only the host's own turns run. */
+	principals?: Pick<IdentityService, "speakerFor">;
+	/**
+	 * The surfaces, so a conversation started over is marked in a channel that shows one, and a
+	 * message that arrives while the host shuts down is told so; without it, neither is.
+	 */
+	surfaces?: Pick<SurfacePort, "of"> & Partial<Pick<SurfacePort, "sendReply">>;
 	/** How long a bare forward waits for the text sent with it; FORWARD_JOIN_MS by default. */
 	forwardJoinMs?: number;
 }
@@ -38,6 +60,12 @@ export function orderClaims(
 	return claims.toSorted((a, b) => b.priority - a.priority);
 }
 
+/** The outcome of a background turn the host did not start because it is shutting down. */
+const stopping = (): ScheduledOutcome => ({
+	status: "skipped",
+	reason: new HostStoppingError().message,
+});
+
 /**
  * Routes every conversation operation to the claim that owns its channel, each inside the
  * channel's queue: messages after joining a bare forward to its text, background turns,
@@ -47,6 +75,12 @@ export class ChannelRouter implements ConversationPort {
 	readonly #options: ChannelRouterOptions;
 	readonly #claims: readonly ChannelClaim[];
 	readonly #forwards: ForwardJoin;
+	/** Each channel's messages being admitted, so they reach their claim and the queue in the order they came. */
+	readonly #admitting = new Map<ChannelKey, Promise<unknown>>();
+	/** The surfaces already warned that their messages carry no actor. */
+	readonly #warned = new Set<string>();
+	/** The channels already told that the host is restarting, so a burst of messages gets one notice. */
+	readonly #told = new Set<ChannelKey>();
 
 	constructor(options: ChannelRouterOptions) {
 		this.#options = options;
@@ -68,45 +102,199 @@ export class ChannelRouter implements ConversationPort {
 	}
 
 	async #route(message: InboundMessage): Promise<void> {
-		const { queue, logger } = this.#options;
 		if (
 			!message.text.trim() &&
 			message.attachments.length === 0 &&
 			!message.forwarded?.text.trim()
 		)
 			return;
-		const admission = this.#owner(message.channel, message.space)?.admit(
-			message,
+		const claim = this.#owner(message.channel, message.space);
+		if (!claim) return;
+		const started = await this.#inOrder(message.channel, async () => {
+			const admission = await this.#admit(claim, message);
+			if (!admission) return undefined;
+			// Once the host shuts down only the turns already running finish: this one starts nothing.
+			if (this.#options.queue.closed) {
+				await this.#refuse(message, admission);
+				return undefined;
+			}
+			return this.#start(message, admission);
+		});
+		await started?.done;
+	}
+
+	/** Runs the channel's admissions one at a time, in the order its messages came. */
+	#inOrder<T>(channel: ChannelKey, task: () => Promise<T>): Promise<T> {
+		const before = this.#admitting.get(channel) ?? Promise.resolve();
+		const run = before.then(task);
+		const after = run.catch(() => undefined);
+		this.#admitting.set(channel, after);
+		void after.then(() => {
+			if (this.#admitting.get(channel) === after)
+				this.#admitting.delete(channel);
+		});
+		return run;
+	}
+
+	/**
+	 * The claim's admission of the message, which carries the speaker its author resolves to; one
+	 * who cannot be resolved, such as while the database is down, reaches the claim as no one. The
+	 * author's contact is recorded, such as their first contact linked, only once the claim takes
+	 * the message, so a message nobody serves links or makes no one. A linked author the rules
+	 * refuse is still recorded as seen at no tier as the message is assessed, whether or not a
+	 * claim then takes it, at most once in a while. When that record fails, or finds them someone
+	 * else or no one now, such as linked elsewhere meanwhile, the message is dropped: it would run
+	 * as a principal that may not exist, such as one only assessed at a first contact. The claim
+	 * hears it through the admission's `dropped` or `unanswered`.
+	 */
+	async #admit(
+		claim: ChannelClaim,
+		message: InboundMessage,
+	): Promise<Admission | undefined> {
+		const { logger, contacts } = this.#options;
+		const { speaker: _given, ...facts } = message;
+		const actor = this.#actorOf(message);
+		let contact: Contact | undefined;
+		if (actor && contacts)
+			try {
+				contact = await contacts.assess(actor, {
+					conversation: message.channel,
+				});
+			} catch (error) {
+				logger.error(
+					{ channel: message.channel, err: error },
+					"could not resolve who wrote a message; it reaches its claim as no one",
+				);
+			}
+		const admission = claim.admit(
+			contact
+				? { ...facts, speaker: Object.freeze({ ...contact.speaker }) }
+				: facts,
 		);
-		if (!admission) return;
-		if (admission.kind === "background") {
-			const outcome = await this.background(admission.turn);
-			if (outcome.status !== "ran") admission.unanswered(outcome);
+		if (!admission || !contact) return admission;
+		try {
+			const taken = await contact.take();
+			if (taken?.principalId === contact.speaker.principalId) return admission;
+			logger.warn(
+				{ channel: message.channel },
+				"the author of a message was linked elsewhere, or refused, while it was admitted; it does not run",
+			);
+		} catch (error) {
+			logger.error(
+				{ channel: message.channel, err: error },
+				"could not record who wrote a message; it does not run",
+			);
+		}
+		if (admission.kind === "turn") admission.dropped?.();
+		else
+			admission.unanswered({
+				status: "skipped",
+				reason: "its author was not who they were when it was admitted",
+			});
+		return undefined;
+	}
+
+	/**
+	 * Who wrote the message, as its surface reports them; a surface that reports no `actor` has it
+	 * read from the author fields under its own name, once warned. None for a bot or an
+	 * integration.
+	 */
+	#actorOf(message: InboundMessage): ActorFacts | undefined {
+		if (message.authorIsBot || message.integration) return undefined;
+		if (message.actor) return message.actor;
+		const { surface } = parseChannelKey(message.channel);
+		if (!this.#warned.has(surface)) {
+			this.#warned.add(surface);
+			this.#options.logger.warn(
+				{ surface },
+				`deprecated: the ${surface} surface reports no InboundMessage.actor, so its authors are read from authorId, authorName, and authorRoleIds as ${surface} identities; set actor, as this goes away in 1.0`,
+			);
+		}
+		return {
+			provider: surface,
+			subject: message.authorId,
+			name: message.authorName,
+			surface,
+			...(message.authorRoleIds
+				? {
+						roles: message.authorRoleIds.map(
+							(role) => `${surface}:role:${role}`,
+						),
+					}
+				: {}),
+			...(message.space ? { space: message.space } : {}),
+			legacyId: message.authorId,
+		};
+	}
+
+	/**
+	 * Drops a message the host no longer starts a turn for because it is shutting down, and tells
+	 * its channel once that it restarts; no one is told for a bot's or an integration's message, such
+	 * as a report, since a notice there would only start the next one.
+	 */
+	async #refuse(message: InboundMessage, admission: Admission): Promise<void> {
+		const { logger, surfaces } = this.#options;
+		const { channel } = message;
+		if (admission.kind === "turn") admission.dropped?.();
+		else
+			admission.unanswered({
+				status: "skipped",
+				reason: new HostStoppingError().message,
+			});
+		logger.info({ channel }, "message not run: the host is shutting down");
+		if (message.authorIsBot || message.integration || this.#told.has(channel))
 			return;
+		this.#told.add(channel);
+		try {
+			await surfaces?.sendReply?.(channel, {
+				chunks: [messages().restartingNotice],
+			});
+		} catch (error) {
+			logger.warn({ channel, err: error }, "restart notice not posted");
+		}
+	}
+
+	/**
+	 * Starts what the claim admitted, in the channel's queue, and returns while it runs: a message
+	 * during a turn is first offered to it, then marked as waiting.
+	 */
+	async #start(
+		message: InboundMessage,
+		admission: Admission,
+	): Promise<{ done: Promise<void> }> {
+		const { queue, logger } = this.#options;
+		if (admission.kind === "background") {
+			const done = this.background(admission.turn).then((outcome) => {
+				if (outcome.status !== "ran") admission.unanswered(outcome);
+			});
+			return { done };
 		}
 		const { busy } = admission;
 		let queued = false;
 		// A message during a turn is added to it when the turn takes it, otherwise marked as waiting.
 		if (busy && queue.size(message.channel) > 0) {
-			if (await busy.steer?.()) {
-				await busy.react(STEERED_MARK);
-				return;
-			}
+			if (await busy.steer?.()) return { done: busy.react(STEERED_MARK) };
 			await busy.react(QUEUED_MARK);
 			queued = true;
 		}
-		await queue
+		const done = queue
 			.run(message.channel, () => {
 				if (queued) void busy?.unreact(QUEUED_MARK);
 				return admission.run();
 			})
 			// pi-lens-ignore: no-unknown-parameters
-			.catch((error: unknown) =>
+			.catch(async (error: unknown) => {
+				// The host began shutting down while this message waited behind a running turn.
+				if (error instanceof HostStoppingError) {
+					if (queued) void busy?.unreact(QUEUED_MARK);
+					return this.#refuse(message, admission);
+				}
 				logger.error(
 					{ channel: message.channel, err: error },
 					admission.failure,
-				),
-			);
+				);
+			});
+		return { done };
 	}
 
 	target(name: string): BackgroundTarget | undefined {
@@ -114,10 +302,12 @@ export class ChannelRouter implements ConversationPort {
 	}
 
 	/**
-	 * A turn nobody wrote, run by the channel's claim inside its queue; never rejects. A turn whose
-	 * target no plugin contributes is skipped, never handed to another target's claim.
+	 * A turn nobody wrote, run by the channel's claim inside its queue, as the speaker its author
+	 * is checked to be; never rejects. A turn whose target no plugin contributes is skipped, never
+	 * handed to another target's claim, and so is one whose author may not run it now.
 	 */
 	async background(turn: BackgroundTurn): Promise<ScheduledOutcome> {
+		if (this.#options.queue.closed) return stopping();
 		if (!this.#options.targets(turn.target))
 			return {
 				status: "skipped",
@@ -131,21 +321,79 @@ export class ChannelRouter implements ConversationPort {
 						status: "skipped",
 						reason: "no conversation takes background turns here",
 					};
-				return claim.background(turn);
+				// Checked as the turn starts, in its place in the queue, so a change meanwhile counts.
+				const runs = await this.runsAs(turn);
+				if ("skipped" in runs)
+					return { status: "skipped", reason: runs.skipped };
+				return claim.background({ ...turn, speaker: runs.speaker });
 			});
 		} catch (error) {
+			if (error instanceof HostStoppingError) return stopping();
 			return { status: "failed", error: String(error) };
 		}
 	}
 
+	/**
+	 * Who a background turn runs as: the system principal for the host's own turn, at its tier;
+	 * otherwise its author's principal, which must exist, be enabled, and hold a tier now, at the
+	 * lower of the turn's tier and theirs. Why not, when it may not run; throws when the identity
+	 * service cannot tell.
+	 */
+	async runsAs(turn: BackgroundTurn): Promise<BackgroundRunsAs> {
+		const { author, tier } = turn;
+		if (!author?.principalId || !tier)
+			return {
+				skipped:
+					"a background turn names its author's principal (author.principalId) and the tier it runs at (tier); this one does not",
+			};
+		if (author.principalId === SYSTEM_PRINCIPAL)
+			return isSystemTurn(turn)
+				? { speaker: { ...systemSpeaker(tier), name: author.name } }
+				: {
+						skipped: `only the host itself starts a turn as the system principal "${SYSTEM_PRINCIPAL}"`,
+					};
+		const { principals } = this.#options;
+		if (!principals)
+			return {
+				skipped: "the host has no identity service to check whom it runs as",
+			};
+		try {
+			const checked = await principals.speakerFor(author.principalId, tier);
+			return {
+				speaker: {
+					id: author.id,
+					name: author.name,
+					tier: checked.tier,
+					principalId: checked.principalId,
+				},
+			};
+		} catch (error) {
+			if (!(error instanceof IdentityError)) throw error;
+			return { skipped: error.message };
+		}
+	}
+
 	startFresh(channel: ChannelKey): Promise<string> {
-		return this.#options.queue.run(channel, () => {
+		return this.#options.queue.run(channel, async () => {
 			const claim = this.#owner(channel);
 			if (!claim) throw new Error(`no conversation owns ${channel}`);
-			return claim.startFresh(channel);
+			const kind = await claim.startFresh(channel);
+			await this.#markFresh(channel);
+			return kind;
 		});
 	}
 
+	/** The restart already counts: a surface that cannot mark it is logged, not failed. */
+	async #markFresh(channel: ChannelKey): Promise<void> {
+		try {
+			await this.#options.surfaces?.of(channel)?.markFresh?.(channel);
+		} catch (error) {
+			this.#options.logger.warn(
+				`could not mark the restart of ${channel}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
 	async deleteConversation(channel: ChannelKey): Promise<"deleted" | "busy"> {
 		const { queue } = this.#options;
 		const claim = this.#owner(channel);
@@ -176,4 +424,9 @@ export class ChannelRouter implements ConversationPort {
 	takesBackground(channel: ChannelKey): boolean {
 		return this.#owner(channel)?.background !== undefined;
 	}
+
+	takesSystemReports(channel: ChannelKey): boolean {
+		const owner = this.#owner(channel);
+		return owner !== undefined && owner.takesSystemReports !== false;
+	}
 }