pi-roundtable 0.8.0 → 0.9.0

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-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);
@@ -176,4 +372,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;
+	}
 }

package/src/core/routing/conversation-turns.ts

@@ -6,9 +6,11 @@ import type {
 } from "../conversations/conversation-registry.ts";
 import type { TurnAttachments } from "../domain/attachment.ts";
 import type { TurnResult } from "../domain/conversation.ts";
+import type { TurnConversation } from "../domain/ports.ts";
 import type { TurnProgress } from "../domain/progress.ts";
 import { PluginError } from "../errors.ts";
 import { messages } from "../i18n/index.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
 import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
@@ -60,8 +62,10 @@ export interface ConversationTurns {
 	 * `turnEnded` with the turn's `kind`, settles a runtime that throws into a failed result, and
 	 * posts the reply, or a failure or stopped notice, through the surface unless `reply` is given.
 	 * It rejects during setup (NotLinkedError), when the host has no runtime to run the turn on,
-	 * and when the conversation cannot be recorded in the host's registry (a database error, or a
-	 * `private` conversation without a speaker). Each of these rejects before the turn starts:
+	 * when the conversation cannot be recorded in the host's registry (a database error, or a
+	 * `private` conversation without a speaker), and when the conversation is recorded private to a
+	 * principal other than the speaker's, unless the speaker is the host's own (`SYSTEM_PRINCIPAL`).
+	 * Each of these rejects before the turn starts:
 	 * nothing is shown, no event is emitted, and `reply` is not called, so a claim that answers
 	 * its person tells them itself.
 	 */
@@ -85,25 +89,50 @@ export interface ConversationTurnsOptions {
 /** The selection of a turn that gives none: the plugins' `agentSelection`. */
 const DEFAULT_SELECTION = "turns";
 
-/** Records the conversation of a turn: private to the speaker when asked, else shared. */
+/**
+ * Records the conversation of a turn, private to the speaker when asked, else shared, and returns
+ * who it belongs to as the record keeps it; without a registry, as the turn asks, if it does.
+ */
 async function record(
 	registry: Pick<ConversationRegistry, "register"> | undefined,
 	input: ConversationTurnInput,
-): Promise<void> {
-	if (!registry) return;
+): Promise<TurnConversation | undefined> {
 	const visibility = input.conversation?.visibility ?? "shared";
 	if (visibility === "private" && !input.speaker)
 		throw new PluginError(
 			`a private conversation needs the speaker it belongs to; ${input.channel} was run without one.`,
 		);
+	if (!registry)
+		return input.conversation && conversationOf(visibility, input.speaker);
 	const title = input.conversation?.title;
-	await registry.register({
+	const kept = await registry.register({
 		key: input.channel,
 		kind: input.kind,
 		visibility,
-		...(visibility === "private" ? { principalId: input.speaker.id } : {}),
+		...(visibility === "private"
+			? { principalId: input.speaker.principalId }
+			: {}),
 		...(title === undefined ? {} : { title }),
 	});
+	if (kept.visibility !== "private" || kept.principalId === undefined)
+		return { visibility: "shared" };
+	// Only its person, or the host itself, speaks in a private conversation: anyone else's turn would
+	// read and act on what is theirs.
+	const { principalId } = input.speaker;
+	if (principalId !== kept.principalId && principalId !== SYSTEM_PRINCIPAL)
+		throw new PluginError(
+			`${input.channel} is private to ${kept.principalId}, so ${principalId} may not speak in it; run their turn in a conversation of their own.`,
+		);
+	return { visibility: "private", principalId: kept.principalId };
+}
+
+function conversationOf(
+	visibility: ConversationVisibility,
+	speaker: Speaker,
+): TurnConversation {
+	return visibility === "private"
+		? { visibility, principalId: speaker.principalId }
+		: { visibility };
 }
 
 export function conversationTurns(
@@ -117,7 +146,7 @@ export function conversationTurns(
 			// A host without a runtime is a setup mistake, so it is refused before anything is shown.
 			const runtime = options.runtime();
 			// A conversation that cannot be recorded runs no turn: who it belongs to would be lost.
-			await record(options.registry?.(), input);
+			const conversation = await record(options.registry?.(), input);
 			const stopTyping = surfaces.startTyping(channel);
 			const hideStop = surfaces.showStop(channel);
 			const turn = { kind, channel, speaker };
@@ -150,6 +179,7 @@ export function conversationTurns(
 								},
 								text: input.text,
 								speaker,
+								...(conversation ? { conversation } : {}),
 								...(input.attachments
 									? { attachments: input.attachments }
 									: {}),

package/src/core/routing/surface-port.ts

@@ -1,13 +1,27 @@
 import type { ChatSurface, SurfacePort } from "../contract/surface.ts";
 import { parseChannelKey } from "../contract/surface.ts";
 import { PluginError } from "../errors.ts";
+import {
+	isPromptScope,
+	type PromptScope,
+	promptScope,
+} from "../interactions/prompts.ts";
 import type { ChannelKey } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+
+export interface SurfacePortOptions {
+	/** Told when a caller uses a form that goes away, such as `prompts(channel, speaker)`. */
+	deprecated?(message: string): void;
+}
 
 /**
  * The port over the contributed surfaces, each chosen by the prefix of a channel's key. `linked`
  * gives the surfaces once every plugin is set up and throws NotLinkedError before.
  */
-export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
+export function surfacePort(
+	linked: () => readonly ChatSurface[],
+	options: SurfacePortOptions = {},
+): SurfacePort {
 	const of = (channel: ChannelKey): ChatSurface | undefined => {
 		const at = channel.indexOf(":");
 		if (at <= 0) return undefined;
@@ -40,10 +54,26 @@ export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
 			of(channel)?.react?.(channel, messageId, emoji),
 		unreact: async (channel, messageId, emoji) =>
 			of(channel)?.unreact?.(channel, messageId, emoji),
-		prompts: (channel, speaker) => of(channel)?.prompts?.(channel, speaker),
+		prompts: (channel, scope) =>
+			of(channel)?.prompts?.(channel, scopeOf(scope, options)),
 		interim: (channel) => of(channel)?.interim?.(channel),
 		progress: async (channel, event) => {
 			await of(channel)?.progress?.(channel, event);
 		},
 	};
 }
+
+/**
+ * The scope a surface's prompts get: as given, or, from the 0.8 form's speaker, theirs in a
+ * shared conversation, as 0.8 had them, with a warning.
+ */
+function scopeOf(
+	given: PromptScope | Speaker | undefined,
+	options: SurfacePortOptions,
+): PromptScope | undefined {
+	if (!given || isPromptScope(given)) return given;
+	options.deprecated?.(
+		"deprecated: prompts(channel, speaker) takes a PromptScope since 0.9, made with promptScope(speaker, visibility); a speaker is read as theirs in a shared conversation, and this form goes away in 1.0",
+	);
+	return promptScope(given);
+}

package/src/core/routing/system-turns.ts

@@ -0,0 +1,29 @@
+import type { BackgroundTurn } from "../contract/channels.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+
+/** The turns the host itself made, by identity: a copy, or one a plugin writes, is not one of them. */
+const made = new WeakSet<BackgroundTurn>();
+
+/**
+ * A background turn the host itself starts as the system principal, such as a logged error's
+ * report or a Discord webhook's post, at the tier its starter gives; the router runs it as the
+ * system principal's speaker. Core-internal: a plugin cannot make one, and a turn it writes naming
+ * the system principal is skipped.
+ */
+export function systemTurn(
+	turn: Omit<BackgroundTurn, "author" | "speaker"> & {
+		author: { id: string; name: string };
+	},
+): BackgroundTurn {
+	const own: BackgroundTurn = {
+		...turn,
+		author: { ...turn.author, principalId: SYSTEM_PRINCIPAL },
+	};
+	made.add(own);
+	return own;
+}
+
+/** Whether the host made this very turn with `systemTurn`. */
+export function isSystemTurn(turn: BackgroundTurn): boolean {
+	return made.has(turn);
+}