pi-roundtable 0.7.19 → 0.9.0

package/src/core/presence/direct-channels.ts

@@ -0,0 +1,104 @@
+import type { SurfacePort } from "../contract/surface.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { Notifier } from "../domain/ports.ts";
+import { splitReply } from "../presentation/reply-splitter.ts";
+
+/**
+ * A way to reach a person on their own, such as a chat network's direct messages or a web inbox.
+ * A plugin contributes it as `directChannels`; the host reaches a person through the first one,
+ * in contribution order, that reaches them.
+ */
+export interface DirectChannelProvider {
+	/** Unique across every plugin, such as `"discord"`. */
+	name: string;
+	/**
+	 * How the `notify` tool names a message sent through it, completing "Send Ada …": such as
+	 * `"a direct message on Discord"`.
+	 */
+	label: string;
+	/**
+	 * The person's own conversation here, where a notice to them is posted and where their
+	 * schedules and delegated reports from a conversation no chat surface carries run; undefined
+	 * when they have none here. It may reach the network and throw when that fails.
+	 */
+	reaches(principalId: string): Promise<ChannelKey | undefined>;
+	/**
+	 * Whether the person has a conversation here, from the host's own records such as their linked
+	 * identities, without reaching the network. A session reads it when it decides whether to offer
+	 * a tool that sends or runs there, so a network outage then does not take the tool away; the
+	 * conversation itself is reached when the tool runs. Without it the host asks `reaches`.
+	 */
+	knows?(principalId: string): Promise<boolean>;
+	/**
+	 * Sends the person a notice here; without it the host posts the text in the channel `reaches`
+	 * names, through the surface that serves it.
+	 */
+	deliver?(principalId: string, text: string): Promise<void>;
+}
+
+/** Where a person was reached: the provider, and their conversation on it. */
+export interface DirectReach {
+	provider: DirectChannelProvider;
+	channel: ChannelKey;
+}
+
+/**
+ * Every plugin's direct channels, as plugins and the core use them. Each call before the host
+ * links its plugins throws NotLinkedError, as for `conversations`.
+ */
+export interface DirectChannels extends Notifier {
+	/** Every contributed provider, in contribution order; empty when no plugin contributes one. */
+	providers(): readonly DirectChannelProvider[];
+	/** The person's own conversation on the first provider that reaches them; undefined when none does. */
+	reach(principalId: string): Promise<DirectReach | undefined>;
+	/**
+	 * The first provider that knows the person, as `DirectChannelProvider.knows` tells without the
+	 * network (or `reaches`, for a provider without it); undefined when none does.
+	 */
+	known(principalId: string): Promise<DirectChannelProvider | undefined>;
+	/**
+	 * Sends the person `text` through the first provider that reaches them; false when none does.
+	 * A provider's failure, such as a network error, rejects.
+	 */
+	notify(principalId: string, text: string): Promise<boolean>;
+}
+
+/** The direct channels over the providers the host linked, posting through its surfaces where a provider does not deliver itself. */
+export function directChannelsPort(
+	providers: () => readonly DirectChannelProvider[],
+	surfaces: Pick<SurfacePort, "sendReply">,
+): DirectChannels {
+	const reach = async (
+		principalId: string,
+	): Promise<DirectReach | undefined> => {
+		for (const provider of providers()) {
+			const channel = await provider.reaches(principalId);
+			if (channel !== undefined) return { provider, channel };
+		}
+		return undefined;
+	};
+	return {
+		providers: () => providers(),
+		reach,
+		known: async (principalId) => {
+			for (const provider of providers()) {
+				const knows = provider.knows
+					? await provider.knows(principalId)
+					: (await provider.reaches(principalId)) !== undefined;
+				if (knows) return provider;
+			}
+			return undefined;
+		},
+		notify: async (principalId, text) => {
+			const reached = await reach(principalId);
+			if (!reached) return false;
+			if (reached.provider.deliver)
+				await reached.provider.deliver(principalId, text);
+			else
+				await surfaces.sendReply(reached.channel, {
+					chunks: splitReply(text),
+				});
+			return true;
+		},
+	};
+}

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/registry/providers.ts

@@ -35,7 +35,7 @@ function defaults(judgeModel: JudgeModel | undefined): Providers {
 		},
 		runtime: () => {
 			throw new ProviderError(
-				"no runtime provider is configured: the agent server builds the Pi runtime when no plugin fills the runtime slot",
+				"no runtime provider is configured: the runtime plugin builds the Pi runtime when no plugin fills the runtime slot; read the running one from services.get(RUNTIME)",
 			);
 		},
 	};

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,21 @@ import {
 	type ScheduledOutcome,
 	STEERED_MARK,
 } from "../contract/channels.ts";
+import { parseChannelKey, type SurfacePort } from "../contract/surface.ts";
+import { IdentityError } from "../domain/errors.ts";
 import { PluginError } from "../errors.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 +33,12 @@ 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; without it, none is. */
+	surfaces?: Pick<SurfacePort, "of">;
 	/** How long a bare forward waits for the text sent with it; FORWARD_JOIN_MS by default. */
 	forwardJoinMs?: number;
 }
@@ -47,6 +65,10 @@ 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>();
 
 	constructor(options: ChannelRouterOptions) {
 		this.#options = options;
@@ -68,34 +90,149 @@ 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);
+			return admission && (await 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 || !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,
+		};
+	}
+
+	/**
+	 * 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 outcome = await this.background(admission.turn);
-			if (outcome.status !== "ran") admission.unanswered(outcome);
-			return;
+			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();
@@ -107,6 +244,7 @@ export class ChannelRouter implements ConversationPort {
 					admission.failure,
 				),
 			);
+		return { done };
 	}
 
 	target(name: string): BackgroundTarget | undefined {
@@ -114,8 +252,9 @@ 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.targets(turn.target))
@@ -131,21 +270,78 @@ 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) {
 			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);
@@ -168,4 +364,17 @@ export class ChannelRouter implements ConversationPort {
 	postsInPlace(channel: ChannelKey): boolean {
 		return this.#owner(channel)?.postsInPlace === true;
 	}
+
+	owns(channel: ChannelKey): boolean {
+		return this.#owner(channel) !== undefined;
+	}
+
+	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;
+	}
 }