pi-roundtable 0.26.3 → 0.27.1

package/src/core/domain/round.ts

@@ -0,0 +1,31 @@
+/**
+ * Where a group's round stands, for a surface that shows it: who speaks now, who is next and who
+ * has spoken. A round is the members' answers to one owner message, one after another; this is what
+ * the core tells a surface at each step, and a surface that shows no rounds never hears it.
+ */
+export type RoundEnd =
+	/** Every member in the order has spoken. */
+	| "done"
+	/** The round reached the most replies a round holds, with members still waiting. */
+	| "limit"
+	/** The owner pressed Stop: the running turn ended and the members waiting did not speak. */
+	| "stopped";
+
+export interface RoundProgress {
+	/** The group message id of the line that opened the round; one round has one id. */
+	id: number;
+	state: "running" | "ended";
+	/** The member speaking now, by name. */
+	current?: string;
+	/** The members still to speak, in order, a handoff appended. */
+	next: string[];
+	/** The members who have replied so far, in order. */
+	spoken: string[];
+	/** The replies made so far, and the most a round holds. */
+	replies: number;
+	limit: number;
+	/** Why a round that has ended ended. */
+	ended?: RoundEnd;
+	/** The owner's messages waiting in the channel for the next round. */
+	queued?: number;
+}

package/src/core/host-registration.ts

@@ -39,6 +39,8 @@ import {
 	type ConversationTurns,
 	conversationTurns,
 } from "./routing/conversation-turns.ts";
+import { MessageObservers } from "./routing/message-observers.ts";
+import { PeerBots } from "./routing/peer-bots.ts";
 import { surfacePort } from "./routing/surface-port.ts";
 import { refuseHostAccess } from "./runtime/chat-only.ts";
 import { CONVERSATIONS, IDENTITY, RUNTIME } from "./services.ts";
@@ -85,6 +87,8 @@ export interface Linked {
  */
 export class Linkage {
 	readonly queue = new ChannelQueue();
+	/** The plugins' passive message observers, shared by the router and `context.observe`. */
+	readonly observers: MessageObservers;
 	readonly events: EventBus;
 	readonly tiers: ToolTierTable;
 	registry: Registry = emptyRegistry();
@@ -113,6 +117,9 @@ export class Linkage {
 		this.#plugins = plugins;
 		this.tiers = options.toolTiers ?? toolTiers();
 		this.events = new EventBus(options.logger);
+		this.observers = new MessageObservers(options.logger, () =>
+			this.#surfaces().roomSurfaces(),
+		);
 	}
 
 	/** Applies the host's environment to the process and returns what plugins read of it. */
@@ -206,6 +213,7 @@ export class Linkage {
 						);
 					return this.registry.dashboard;
 				},
+				observe: (filter, observer) => this.observers.add(filter, observer),
 				apiKey: async (provider) => this.#options.apiKey?.(provider),
 				listener: (id) => listenerAddress(listeners, id),
 			},
@@ -226,6 +234,10 @@ export class Linkage {
 			queue: this.queue,
 			surfaces: this.#surfaces(),
 			logger,
+			observers: this.observers,
+			...(this.#options.peerBots
+				? { peerBots: new PeerBots(this.#options.peerBots) }
+				: {}),
 			...(this.#options.conversations?.forwardJoinMs === undefined
 				? {}
 				: { forwardJoinMs: this.#options.conversations.forwardJoinMs }),
@@ -259,6 +271,9 @@ export class Linkage {
 		};
 		return {
 			handle: (message) => router().handle(message),
+			messageDeleted: (channel, id, space) =>
+				router().messageDeleted(channel, id, space),
+			messageEdited: (message) => router().messageEdited(message),
 			background: (turn) => router().background(turn),
 			runsAs: (turn) => router().runsAs(turn),
 			target: (name) => router().target(name),

package/src/core/host.ts

@@ -12,6 +12,7 @@ import type { Locale } from "./i18n/index.ts";
 import type { JudgeModel } from "./judging/model-judge.ts";
 import type { Logger } from "./log.ts";
 import type { AgentTools, RoundtablePlugin, Service } from "./plugin.ts";
+import type { PeerBotsConfig } from "./routing/peer-bots.ts";
 import { RUNTIME } from "./services.ts";
 import type { ChannelKey } from "./sessions.ts";
 import type { ToolTierTable } from "./tool-tiers.ts";
@@ -50,6 +51,11 @@ export interface RoundtableOptions {
 	conversations?: {
 		forwardJoinMs?: number;
 	};
+	/**
+	 * The other bots on Discord whose mentions and replies are answered like a guest's (what
+	 * `discord.peerBots` sets); without it no bot is. Stops the start for an id that is not a Discord id.
+	 */
+	peerBots?: PeerBotsConfig;
 	/** The model the default judge asks, when no plugin provides a judge. */
 	judgeModel?: JudgeModel;
 	/**

package/src/core/i18n/conversation.ts

@@ -16,6 +16,8 @@ export function conversationEn(ctx: CatalogContext) {
 		restartingNotice: `-# ${ctx.assistant} is restarting and takes no new messages right now; please send this again in a few minutes.`,
 		roundLimitNotice:
 			"-# This round already has 8 replies, so it stops here; call us again if you need more.",
+		roundStoppedNotice:
+			"-# The round was stopped, so the members still waiting did not speak.",
 		restartNotice: `-# ${ctx.assistant} restarted before this job finished, so nothing more will be reported here.`,
 		threadStarted: (name: string, thread: string | undefined) =>
 			thread ? `🧵 Started: ${name} → ${thread}` : `🧵 Started: ${name}`,
@@ -48,6 +50,7 @@ export function conversationZhTW(
 		restartingNotice: `-# ${ctx.assistant} 正在重新啟動，暫時不接新訊息；請過幾分鐘再傳一次。`,
 		roundLimitNotice:
 			"-# 這一輪已經有 8 則回覆，先停在這裡；需要的話請再叫我們。",
+		roundStoppedNotice: "-# 本輪已停止，還沒輪到的成員不再發言。",
 		restartNotice: `-# ${ctx.assistant} 在這項工作結束前重新啟動了，這裡不會再有回報。`,
 		threadStarted: (name: string, thread: string | undefined) =>
 			thread ? `🧵 開始：${name} → ${thread}` : `🧵 開始：${name}`,

package/src/core/i18n/dashboard.ts

@@ -20,6 +20,8 @@ export function dashboardEn(ctx: CatalogContext) {
 		dashNotActive: "No activity since startup",
 		dashAgentFooter: (schedules: number, last: string) =>
 			`-# Schedules ${schedules} · ${last}`,
+		dashHelpers: (count: number, working: number) =>
+			`-# ${count} temp knight${count === 1 ? "" : "s"}, ${working} working`,
 		dashGroupBusy: (busy: number) => `🟠 ${busy} in progress`,
 		dashGroupMembers: (members: readonly string[], host: string) =>
 			`Members: ${members.join(", ")} | Host: ${host}`,
@@ -56,6 +58,8 @@ export function dashboardZhTW(
 		dashNotActive: "啟動後尚未活動",
 		dashAgentFooter: (schedules: number, last: string) =>
 			`-# 排程 ${schedules} · ${last}`,
+		dashHelpers: (count: number, working: number) =>
+			`-# 臨時騎士 ${count} 位，${working} 位工作中`,
 		dashGroupBusy: (busy: number) => `🟠 進行中（${busy} 則）`,
 		dashGroupMembers: (members: readonly string[], host: string) =>
 			`成員：${members.join("、")}｜主持：${host}`,

package/src/core/ops/error-reporter.ts

@@ -46,6 +46,8 @@ export interface ErrorReporterOptions {
 	destination: ErrorReportDestination;
 	/** The name the reports give the process, such as "Roundtable". */
 	app: string;
+	/** The configuration key the destination was written under, as startup errors name it; default `ops.conversation`. */
+	configKey?: string;
 	ignored?: readonly RegExp[];
 	/** Replaceable in tests. */
 	now?: () => number;
@@ -62,6 +64,7 @@ export interface ErrorReporterOptions {
  */
 export class ErrorReporter {
 	readonly destination: ErrorReportDestination;
+	readonly configKey: string;
 	readonly #app: string;
 	readonly #ignored: readonly RegExp[];
 	readonly #now: () => number;
@@ -80,6 +83,7 @@ export class ErrorReporter {
 
 	constructor(options: ErrorReporterOptions) {
 		this.destination = options.destination;
+		this.configKey = options.configKey ?? "ops.conversation";
 		this.#app = options.app;
 		this.#ignored = options.ignored ?? IGNORED_ERRORS;
 		this.#now = options.now ?? Date.now;

package/src/core/ops/ops-alerts.ts

@@ -4,14 +4,51 @@ import { AlertThrottle } from "./alert-throttle.ts";
 const DEFAULT_WINDOW_MS = 60 * 60_000;
 const DEFAULT_KIND_CAP = 8;
 
+/** How serious a raised alert says it is; only the sink reads it, to choose a picture or a route. */
+export type OpsSeverity = "info" | "warning" | "critical";
+
+/** What the sink is told about an alert besides its text. */
+export interface OpsAlert {
+	/** The key's word before the first colon. */
+	kind: string;
+	/** The key the alert was raised under; `OpsAlerts.resolve` takes it. */
+	key: string;
+	/** The short code given to `raise`, when there was one. */
+	code?: string;
+	/** Set when the alert is news, not a fault. */
+	info?: true;
+	/** The severity given to `raise`, when there was one. */
+	severity?: OpsSeverity;
+}
+
+/** What the sink is told when an alert's fault is over. */
+export interface OpsResolution {
+	kind: string;
+	key: string;
+}
+
+/**
+ * Posts one alert's text where the people who run the host read it. Resolves true when it was
+ * posted and false when the sink chose not to (it logs why itself); a throw is a failed post. A sink
+ * written to take only the text still fits: the second argument is simply not read.
+ */
+export interface OpsSink {
+	(text: string, alert: OpsAlert): Promise<boolean>;
+	/**
+	 * Called when `OpsAlerts.resolve` ends a fault whose alert was posted, so the sink can mark that
+	 * alert as recovered, such as editing its message. A throw is logged by its name and never
+	 * reaches the caller of `resolve`.
+	 */
+	resolved?(event: OpsResolution): Promise<void> | void;
+}
+
 export interface OpsAlertsOptions {
 	/**
-	 * Posts one alert's text where the people who run the host read it. Resolves true when it was
-	 * posted and false when the sink chose not to (it logs why itself); a throw is a failed post.
-	 * Either way the key and the slot are given back, so the next raise tries again. Absent: alerts are
-	 * only recorded and logged, the key still held so the log has one line per window.
+	 * Where alerts are posted. Either way a post ends, the key and the slot are given back when it
+	 * did not succeed, so the next raise tries again. Absent: alerts are only recorded and logged,
+	 * the key still held so the log has one line per window.
 	 */
-	sink?: (text: string) => Promise<boolean>;
+	sink?: OpsSink;
 	logger: Logger;
 	/** What `faults()` calls each kind; a kind not listed is called by itself. */
 	kinds?: Readonly<Record<string, string>>;
@@ -27,6 +64,8 @@ export interface OpsRaiseOptions {
 	code?: string;
 	/** News, not a fault: posted at most once per key, not counted against the kind's cap, not listed. */
 	info?: boolean;
+	/** Passed to the sink with the text; nothing in `OpsAlerts` reads it. */
+	severity?: OpsSeverity;
 }
 
 /** The last fault of one kind since the start, and how often it came. */
@@ -39,8 +78,17 @@ export interface OpsAlertKind {
 	raised: number;
 	/** Of those, held back because the key or the kind had been raised inside the window. */
 	suppressed: number;
+	/**
+	 * When `resolve` ended the kind's last open alert, and no fault of the kind has been raised
+	 * since; absent while the kind has an alert posted and not resolved, or none was ever
+	 * resolved.
+	 */
+	clearedAt?: number;
 }
 
+/** The most posted alerts `resolve` remembers; the oldest is forgotten past it. */
+const POSTED_CAP = 1_000;
+
 /** The kind of an alert is the word before the first colon of its key. */
 function kindOf(key: string): string {
 	const colon = key.indexOf(":");
@@ -58,6 +106,8 @@ export class OpsAlerts {
 	readonly #options: OpsAlertsOptions;
 	readonly #throttle: AlertThrottle;
 	readonly #kinds = new Map<string, OpsAlertKind>();
+	/** The faults posted and not resolved, oldest first, by key. */
+	readonly #posted = new Map<string, string>();
 
 	constructor(options: OpsAlertsOptions) {
 		this.#options = options;
@@ -78,6 +128,33 @@ export class OpsAlerts {
 		return [...this.#kinds.values()].sort((a, b) => b.at - a.at);
 	}
 
+	/**
+	 * Says the fault of a key is over: gives the key back, so a new fault under it posts again, calls
+	 * the sink's `resolved` when the key's alert was posted, and marks the kind in `faults()` as
+	 * cleared once none of its alerts is open. Resolving a key that was not posted, or that is
+	 * already resolved, does nothing, and so does resolving one whose post has not finished.
+	 * Never throws; whether it ended an open alert.
+	 */
+	async resolve(key: string): Promise<boolean> {
+		const { sink, logger } = this.#options;
+		const kind = this.#posted.get(key);
+		if (kind === undefined) return false;
+		this.#posted.delete(key);
+		this.#throttle.release(key);
+		const entry = this.#kinds.get(kind);
+		if (entry && ![...this.#posted.values()].includes(kind))
+			entry.clearedAt = (this.#options.now ?? Date.now)();
+		try {
+			await sink?.resolved?.({ kind, key });
+		} catch (error) {
+			logger.warn(
+				{ error: error instanceof Error ? error.name : "unknown" },
+				"an ops alert's recovery could not be posted",
+			);
+		}
+		return true;
+	}
+
 	/** Posts the alert unless its key or its kind is held inside the window; whether it was posted. */
 	async raise(
 		key: string,
@@ -103,7 +180,17 @@ export class OpsAlerts {
 		if (!info) this.#throttle.slot(kind);
 		const undo = () => this.#throttle.release(key, info ? undefined : kind);
 		try {
-			if (await sink(text)) return true;
+			const sent = await sink(text, {
+				kind,
+				key,
+				...(options.code ? { code: options.code } : {}),
+				...(info ? { info: true as const } : {}),
+				...(options.severity ? { severity: options.severity } : {}),
+			});
+			if (sent) {
+				if (!info) this.#open(key, kind);
+				return true;
+			}
 			undo();
 			return false;
 		} catch (error) {
@@ -117,6 +204,15 @@ export class OpsAlerts {
 		}
 	}
 
+	#open(key: string, kind: string): void {
+		this.#posted.delete(key);
+		this.#posted.set(key, kind);
+		for (const old of this.#posted.keys()) {
+			if (this.#posted.size <= POSTED_CAP) break;
+			this.#posted.delete(old);
+		}
+	}
+
 	#record(kind: string, code: string | undefined, suppressed: boolean): void {
 		const before = this.#kinds.get(kind);
 		const { kinds, now } = this.#options;

package/src/core/plugin.ts

@@ -6,6 +6,8 @@ import type {
 	BackgroundTarget,
 	ChannelClaim,
 	ConversationPort,
+	MessageObserver,
+	ObserveFilter,
 	QueuePort,
 } from "./contract/channels.ts";
 import type { Providers, ResolvedProviders } from "./contract/providers.ts";
@@ -335,6 +337,21 @@ export interface PluginContext {
 	events: EventSink;
 	/** The claimed channels' conversations; calls during setup throw NotLinkedError. */
 	conversations: ConversationPort;
+	/**
+	 * Hears every inbound message the filter matches, whichever claim owns its channel, without
+	 * admitting, blocking or delaying it: the observer runs after routing has begun and cannot
+	 * change the message the claims get. It hears what the router considers: people's messages,
+	 * those of a bot the host lists as a peer, and an integration's (such as a webhook's) with
+	 * `integration` set; never an unlisted bot's, never the assistant's own, and never a message
+	 * in a channel no claim owns. It does not hear direct conversations unless the filter says
+	 * `includeDirect`, and not the rooms of a surface that hosts agent rooms unless the filter
+	 * names that surface. The message is a copy without a `speaker`, as no one is resolved for an
+	 * observer. Observers see untrusted text from other people: keep it out of logs, hold it no
+	 * longer than needed, and treat it as private to the people who wrote it. A throw or rejection
+	 * is logged and never reaches routing or another observer. Returns a function that stops it.
+	 * May be called during setup.
+	 */
+	observe(filter: ObserveFilter, observer: MessageObserver): () => void;
 	/**
 	 * Files a plugin takes from a person outside a turn, such as an upload, kept for a conversation
 	 * until a turn uses them; a call throws PluginError when the host has no `dataDir`.

package/src/core/registry/contributions.ts

@@ -34,6 +34,7 @@ import {
 import { TIERS } from "../speakers.ts";
 import type { ToolTierTable } from "../tool-tiers.ts";
 import { ServiceRegistry } from "./services.ts";
+import { surfaceService } from "./surface-service.ts";
 
 /** Everything the plugins contributed, in contribution order. */
 export interface Registry {
@@ -273,32 +274,6 @@ function checkSurfacePrefix(plugin: string, prefix: unknown): void {
 		);
 }
 
-/**
- * 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

package/src/core/registry/surface-service.ts

@@ -0,0 +1,41 @@
+import type { ChatSurface } from "../contract/surface.ts";
+import type { PluginContext, Service } from "../plugin.ts";
+
+/**
+ * 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. It also passes the surface the router's
+ * delete and edit events for its own channels.
+ */
+export 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);
+				},
+				{
+					deleted: (channel, messageId, space) => {
+						if (!channel.startsWith(`${surface.surface}:`)) return;
+						void conversations.messageDeleted?.(channel, messageId, space);
+					},
+					edited: (message) => {
+						if (!message.channel.startsWith(`${surface.surface}:`)) return;
+						void conversations.messageEdited?.(message);
+					},
+				},
+			),
+		...(surface.stop ? { stop: () => surface.stop?.() } : {}),
+	};
+}

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

@@ -24,7 +24,10 @@ 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 { tellDeleted, tellEdited } from "./claim-events.ts";
 import { ForwardJoin } from "./forward-join.ts";
+import type { MessageObservers } from "./message-observers.ts";
+import { type PeerBots, peerFacts } from "./peer-bots.ts";
 import { isSystemTurn } from "./system-turns.ts";
 
 export interface ChannelRouterOptions {
@@ -45,6 +48,10 @@ export interface ChannelRouterOptions {
 	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;
+	/** The other bots whose messages are answered like a guest's, with the rounds they get; without it, no bot's. */
+	peerBots?: PeerBots;
+	/** The plugins' passive listeners; each message that reaches routing in an owned channel is handed to them. */
+	observers?: MessageObservers;
 }
 
 /** Claims by descending priority, keeping registration order among equals; refuses a repeated name. */
@@ -101,7 +108,16 @@ export class ChannelRouter implements ConversationPort {
 		return this.#forwards.handle(message, (m) => this.#route(m));
 	}
 
-	async #route(message: InboundMessage): Promise<void> {
+	async #route(given: InboundMessage): Promise<void> {
+		// Only the router says a message is a peer bot's or who its speaker is.
+		const { peerBot: _peer, speaker: _speaker, ...plain } = given;
+		const peers = this.#options.peerBots;
+		if (peers && !plain.authorIsBot && !plain.integration)
+			peers.personPosted(plain.channel);
+		const listed = peers?.lists(plain) === true;
+		const message: InboundMessage = listed
+			? { ...peerFacts(plain), peerBot: true }
+			: plain;
 		if (
 			!message.text.trim() &&
 			message.attachments.length === 0 &&
@@ -110,9 +126,20 @@ export class ChannelRouter implements ConversationPort {
 			return;
 		const claim = this.#owner(message.channel, message.space);
 		if (!claim) return;
+		// A bot nobody lists is not heard, as it is not answered; a listed peer is, rounds or not.
+		if (!message.authorIsBot || message.peerBot || message.integration)
+			this.#options.observers?.notify(message);
 		const started = await this.#inOrder(message.channel, async () => {
+			if (listed && peers?.exhausted(message.channel)) {
+				this.#options.logger.info(
+					{ channel: message.channel, bot: message.authorId },
+					"peer bot message ignored: its rounds in this channel are used up until a person posts",
+				);
+				return undefined;
+			}
 			const admission = await this.#admit(claim, message);
 			if (!admission) return undefined;
+			if (listed) peers?.answered(message.channel);
 			// 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);
@@ -197,10 +224,11 @@ export class ChannelRouter implements ConversationPort {
 	/**
 	 * 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.
+	 * integration, unless the host lists the bot as a peer.
 	 */
 	#actorOf(message: InboundMessage): ActorFacts | undefined {
-		if (message.authorIsBot || message.integration) return undefined;
+		if ((message.authorIsBot && !message.peerBot) || message.integration)
+			return undefined;
 		if (message.actor) return message.actor;
 		const { surface } = parseChannelKey(message.channel);
 		if (!this.#warned.has(surface)) {
@@ -297,6 +325,29 @@ export class ChannelRouter implements ConversationPort {
 		return { done };
 	}
 
+	/** Tells the claim that owns the channel a message was deleted; never rejects, never waits for the channel's queue. */
+	messageDeleted(
+		channel: ChannelKey,
+		messageId: string,
+		space?: string,
+	): Promise<void> {
+		return tellDeleted(
+			this.#owner(channel, space),
+			channel,
+			messageId,
+			this.#options.logger,
+		);
+	}
+
+	/** Tells the claim that owns the channel a message was edited; never rejects, never waits for the channel's queue. */
+	messageEdited(message: InboundMessage): Promise<void> {
+		return tellEdited(
+			this.#owner(message.channel, message.space),
+			message,
+			this.#options.logger,
+		);
+	}
+
 	target(name: string): BackgroundTarget | undefined {
 		return this.#options.targets(name);
 	}

package/src/core/routing/claim-events.ts

@@ -0,0 +1,42 @@
+import type { ChannelClaim, InboundMessage } from "../contract/channels.ts";
+import type { Logger } from "../log.ts";
+import type { ChannelKey } from "../sessions.ts";
+
+/** Tells the claim a message in its channel was deleted; a claim without the hook, or none, is skipped. Never rejects. */
+export async function tellDeleted(
+	claim: ChannelClaim | undefined,
+	channel: ChannelKey,
+	messageId: string,
+	logger: Logger,
+): Promise<void> {
+	if (!claim?.onMessageDeleted) return;
+	try {
+		await claim.onMessageDeleted(channel, messageId);
+	} catch (error) {
+		logger.warn(
+			{ channel, claim: claim.name, err: error },
+			"a claim failed to handle a deleted message",
+		);
+	}
+}
+
+/**
+ * Tells the claim a message in its channel was edited. Nobody is resolved or admitted for an edit,
+ * so what only the router sets (`speaker`, `peerBot`) is dropped. Never rejects.
+ */
+export async function tellEdited(
+	claim: ChannelClaim | undefined,
+	given: InboundMessage,
+	logger: Logger,
+): Promise<void> {
+	if (!claim?.onMessageEdited) return;
+	const { peerBot: _peer, speaker: _speaker, ...message } = given;
+	try {
+		await claim.onMessageEdited(message);
+	} catch (error) {
+		logger.warn(
+			{ channel: message.channel, claim: claim.name, err: error },
+			"a claim failed to handle an edited message",
+		);
+	}
+}

package/src/core/routing/message-observers.ts

@@ -0,0 +1,86 @@
+import type {
+	InboundMessage,
+	MessageObserver,
+	ObserveFilter,
+} from "../contract/channels.ts";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { Logger } from "../log.ts";
+
+interface Registered {
+	filter: Readonly<ObserveFilter>;
+	observer: MessageObserver;
+}
+
+/**
+ * Whether the filter lets the message through. A direct message passes only when the filter asks
+ * for it, and a message of a surface that hosts private rooms only when the filter names that
+ * surface.
+ */
+function matches(
+	filter: Readonly<ObserveFilter>,
+	message: InboundMessage,
+	rooms: ReadonlySet<string>,
+) {
+	if (message.isDirect && filter.includeDirect !== true) return false;
+	const { surface } = parseChannelKey(message.channel);
+	if (filter.surface !== undefined && surface !== filter.surface) return false;
+	if (filter.surface === undefined && rooms.has(surface)) return false;
+	if (filter.space !== undefined && message.space !== filter.space)
+		return false;
+	if (filter.channels && !filter.channels.includes(message.channel))
+		return false;
+	return true;
+}
+
+/**
+ * The plugins' passive listeners on inbound messages. `notify` hands each matching observer its
+ * own frozen copy on a later tick and returns at once, so an observer cannot hold up, change or
+ * fail the routing of the message it hears; its errors are logged by name, never with the text.
+ */
+export class MessageObservers {
+	readonly #logger: Logger;
+	readonly #observers = new Set<Registered>();
+	readonly #rooms: () => readonly string[];
+
+	/**
+	 * `rooms` names the surfaces that host private rooms (`agentRooms`); a filter that does not
+	 * name the surface does not hear their messages. It is read for each message, since surfaces
+	 * are linked after the observers are made.
+	 */
+	constructor(logger: Logger, rooms: () => readonly string[] = () => []) {
+		this.#logger = logger;
+		this.#rooms = rooms;
+	}
+
+	/** Registers an observer; the returned function removes it. */
+	add(filter: ObserveFilter, observer: MessageObserver): () => void {
+		const entry = { filter: { ...filter }, observer };
+		this.#observers.add(entry);
+		return () => {
+			this.#observers.delete(entry);
+		};
+	}
+
+	/** Hands the message to every observer whose filter matches; never throws. */
+	notify(message: InboundMessage): void {
+		for (const { filter, observer } of this.#observers) {
+			// Anything that throws here, such as a value that cannot be cloned, is the observer's loss.
+			try {
+				if (!matches(filter, message, new Set(this.#rooms()))) continue;
+				const copy = Object.freeze(structuredClone(message));
+				void Promise.resolve()
+					.then(() => observer(copy))
+					.catch((error: unknown) => this.#failed(error));
+			} catch (error) {
+				this.#failed(error);
+			}
+		}
+	}
+
+	#failed(error: unknown): void {
+		this.#logger.warn(
+			{ error: error instanceof Error ? error.name : "unknown" },
+			"a message observer failed",
+		);
+	}
+}