pi-roundtable 0.28.0 → 0.29.1

package/src/core/agents/team-helpers.ts

@@ -1,7 +1,8 @@
 import { helpersOf } from "../config/helpers.ts";
 import { AgentError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
-import { isHelper } from "./agent-rules.ts";
+import { surfaceOf } from "../presence/delivery-router.ts";
+import { answersTo, helperSurface, isHelper } from "./agent-rules.ts";
 import type { Agent } from "./agent-store.ts";
 import type { HelpersEnded } from "./helper-ops.ts";
 import type { TeamContext } from "./team-options.ts";
@@ -11,8 +12,9 @@ const SWEEP_EVERY_MS = 3_600_000;
 
 /**
  * The team's temp knights after they are made: which a knight has, which are finished, and their
- * archive, restore, and sweep. Archiving one closes its Discord thread, since a temp knight's
- * place is a thread of its parent's channel; an archived one keeps its history.
+ * archive, restore, and sweep. A temp knight made on Discord lives in a thread of its parent's
+ * channel; one made in the web app gets that thread only once someone reaches for it on Discord.
+ * Archiving one closes its thread, when it has one; an archived one keeps its history.
  */
 export class TeamHelpers {
 	readonly #ctx: TeamContext;
@@ -20,6 +22,8 @@ export class TeamHelpers {
 	readonly #archiveAgent: (agent: Agent) => Promise<void>;
 	readonly #ended: ((event: HelpersEnded) => void)[] = [];
 	#sweeper: ReturnType<typeof setInterval> | undefined;
+	/** The threads being made for web-born temp knights, by name, so two reaches make one. */
+	readonly #placing = new Map<string, Promise<void>>();
 
 	constructor(ctx: TeamContext, archiveAgent: (agent: Agent) => Promise<void>) {
 		this.#ctx = ctx;
@@ -125,9 +129,74 @@ export class TeamHelpers {
 		return restored;
 	}
 
+	/**
+	 * A `message_agent` call that names "discord", or names nothing from a Discord conversation, gives
+	 * a web-born temp knight its thread first.
+	 */
+	async reach(
+		caller: AgentTurnScope,
+		to: string,
+		conversation?: string,
+	): Promise<void> {
+		const { store } = this.#ctx.options;
+		const { turns } = this.#ctx;
+		const target = store.agent(to);
+		const speaker = turns.speakerOf(caller);
+		const from = turns.turnChannel(caller);
+		// Unnamed, a message stays on the sender's surface, so one sent from Discord goes there too.
+		const wanted = conversation?.trim() || surfaceOf(from);
+		if (wanted !== "discord" || !target || !speaker) return;
+		if (answersTo(target, caller.name, from, speaker))
+			await this.placeOnDiscord(to);
+	}
+
+	/**
+	 * Gives an active temp knight made in the web app its thread under the parent's channel, the
+	 * first time someone reaches for it on Discord. One made on Discord, or before the origin was
+	 * kept, already has its place, and a host without Discord threads makes none; never rejects.
+	 */
+	placeOnDiscord(name: string): Promise<void> {
+		const pending = this.#placing.get(name);
+		if (pending) return pending;
+		const placing = this.#placeOnDiscord(name).finally(() =>
+			this.#placing.delete(name),
+		);
+		this.#placing.set(name, placing);
+		return placing;
+	}
+
+	async #placeOnDiscord(name: string): Promise<void> {
+		const { store, channels, logger } = this.#ctx.options;
+		const agent = store.agent(name);
+		const surface = helperSurface(agent);
+		if (agent?.status !== "active" || agent.channelId) return;
+		if (surface === undefined || surface === "discord") return;
+		const parent = store.agent(agent.parent as string);
+		if (!parent?.channelId || !channels?.createThread) return;
+		try {
+			const channelId = await channels.createThread(
+				parent.channelId,
+				agent.displayName,
+			);
+			await store.updateAgent(name, { channelId });
+		} catch (error) {
+			logger.warn(
+				{ agent: name, err: error },
+				"temp knight's thread not made; it stays in its rooms",
+			);
+			return;
+		}
+		logger.info(
+			{ agent: name, parent: parent.name },
+			"temp knight's thread made",
+		);
+		this.#ctx.changed();
+	}
+
 	/**
 	 * Restores one archived temp knight: its thread opens again, or a new one is made when the old
-	 * is gone. It comes back finished, with nothing running.
+	 * is gone. One made in the web app never gets a new thread: its old one reopens, if it had one
+	 * that is still there. It comes back finished, with nothing running.
 	 */
 	async restoreOne(agent: Agent): Promise<void> {
 		const { store, channels, logger } = this.#ctx.options;
@@ -137,6 +206,8 @@ export class TeamHelpers {
 				`"${agent.name}" belongs to "${agent.parent}", which is archived; restore it first.`,
 			);
 		let { channelId } = agent;
+		const surface = helperSurface(agent);
+		const bornOnDiscord = surface === undefined || surface === "discord";
 		if (channels?.createThread && parent.channelId) {
 			if (
 				channelId &&
@@ -144,7 +215,7 @@ export class TeamHelpers {
 				(await channels.exists(channelId))
 			)
 				await channels.openThread(channelId);
-			else
+			else if (bornOnDiscord)
 				channelId = await channels.createThread(
 					parent.channelId,
 					agent.displayName,

package/src/core/agents/team-keys.ts

@@ -87,6 +87,20 @@ export const roomSurfaceOf = (room: ChannelKey): string | undefined => {
 	return surface === DISCORD_SURFACE ? undefined : surface;
 };
 
+/**
+ * The channel a group seat runs in outside a running turn: the group's room on the surface of the
+ * seat's home for a room seat, so it never falls out to the group's Discord channel; otherwise the
+ * group's Discord channel, or the seat's home.
+ */
+export function groupSeatChannel(
+	group: Pick<AgentGroup, "name" | "channelId">,
+	scope: Pick<AgentTurnScope, "home">,
+): ChannelKey {
+	const surface = roomSurfaceOf(scope.home);
+	if (surface !== undefined) return groupRoomKey(surface, group.name);
+	return group.channelId ? discordKey(group.channelId) : scope.home;
+}
+
 /**
  * An agent's conversation inside a group, apart from its own. In a Discord group channel, or
  * without a room, it is keyed by the channel; in a room of another surface, by the surface and the

package/src/core/agents/team-turns.ts

@@ -31,6 +31,7 @@ import {
 	coordinatorOf,
 	discordIdOf,
 	discordKey,
+	groupSeatChannel,
 	scopeOf,
 } from "./team-keys.ts";
 import {
@@ -429,10 +430,7 @@ export class TeamTurns {
 			: undefined;
 		if (!group) return scope.home;
 		// A seat of a room's group runs in that room; its running turn knows which.
-		return (
-			this.#posting.get(scope.session) ??
-			(group.channelId ? discordKey(group.channelId) : scope.home)
-		);
+		return this.#posting.get(scope.session) ?? groupSeatChannel(group, scope);
 	}
 
 	/**

package/src/core/builtin/modules.ts

@@ -31,6 +31,7 @@ import { Scheduler } from "../modules/schedules/scheduler.ts";
 import { schedulesExtension } from "../modules/schedules/schedules.ts";
 import type { ErrorReporter } from "../ops/error-reporter.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
+import { runChannelFor } from "../presence/delivery-router.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import {
 	AGENTS,
@@ -130,23 +131,22 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 				services.get(AGENTS).team.roomsOf(agent);
 			// A conversation no chat surface carries keeps its runs in the creator's direct messages, where
 			// a claim must take them; anyone's elsewhere would run in a conversation that is not theirs.
-			const channelFor = async (
+			// The delivery router picks those messages with the conversation as the origin.
+			const channelFor = (
 				channel: ChannelKey,
 				principalId: string,
 				refused: (message: string) => Error,
-			) => {
-				if (surfaces.of(channel)) return channel;
-				const reached = await directChannels.reach(principalId);
-				if (!reached)
-					throw refused(
-						"this conversation has no chat surface to post a run in, and you have no direct channel on this host to post it in instead",
-					);
-				if (!conversations.takesBackground(reached.channel))
-					throw refused(
-						`this conversation has no chat surface to post a run in, and nothing here takes background turns in your ${reached.provider.name} direct messages, where it would go instead`,
-					);
-				return reached.channel;
-			};
+			) =>
+				runChannelFor(
+					{
+						surfaces,
+						directChannels,
+						takesBackground: (key) => conversations.takesBackground(key),
+					},
+					channel,
+					principalId,
+					refused,
+				);
 			const scheduleChannelFor = (channel: ChannelKey, principalId: string) =>
 				channelFor(channel, principalId, (m) => new ScheduleError(m));
 			const delegateChannelFor = (channel: ChannelKey, principalId: string) =>
@@ -198,7 +198,7 @@ export function modulesPlugin(options: ModulesOptions): RoundtablePlugin {
 					// Only whether a direct channel knows them, without the network; the conversation there,
 					// and whether a claim takes its turns, are checked when a tool runs.
 					try {
-						if (!(await directChannels.known(own))) return;
+						if (!(await directChannels.known(home, own))) return;
 					} catch (error) {
 						logger.warn(
 							{ channel: home, err: error },

package/src/core/config/routing.ts

@@ -31,11 +31,12 @@ export interface AgentRoutes {
 	 */
 	integration?: "origin" | "primary" | (string & {});
 	/**
-	 * The conversation a `message_agent` call reaches when it names none. `"latest"` (default) is
-	 * the one the agent last ran a turn in, never carrying a message from a room out to Discord;
+	 * The conversation a `message_agent` call reaches when it names none. `"origin-surface"`
+	 * (default) is the agent's place on the sender's surface, else its primary place; `"latest"` the
+	 * one the agent last ran a turn in on the sender's surface, else as `"origin-surface"`;
 	 * `"primary"` the agent's primary place; a surface name the agent's place there.
 	 */
-	agentMessage?: "latest" | "primary" | (string & {});
+	agentMessage?: "origin-surface" | "latest" | "primary" | (string & {});
 	/**
 	 * Where an agent's opening task (`agent_create task`) runs. `"origin-surface"` (default) is the
 	 * agent's place on the surface the creation came from, else its primary place; `"primary"`
@@ -86,7 +87,7 @@ const DECLARED_PLACES: readonly string[] = ["ops"];
 export const ROUTE_WORDS = {
 	primary: ["auto"],
 	integration: ["origin", "primary"],
-	agentMessage: ["latest", "primary"],
+	agentMessage: ["origin-surface", "latest", "primary"],
 	opening: ["origin-surface", "primary"],
 } as const;
 

package/src/core/contract/channels.ts

@@ -109,6 +109,31 @@ export interface InboundMessage {
 export const STEERED_MARK = "↪️";
 export const QUEUED_MARK = "⏳";
 
+/** A message waiting in a channel's queue for its own turn (`ConversationPort.queued`). */
+export interface QueuedMessage {
+	/** The surface's id of the message, as `InboundMessage.messageId`. */
+	messageId: string;
+	/** The principal of the person who wrote it; absent when the router resolved none. */
+	principalId?: string;
+	/** What its turn will use: the text as last edited. */
+	text: string;
+	/** Epoch milliseconds when it was queued. */
+	queuedAt: number;
+}
+
+/** Who asks to change a queued message; only its author may. */
+export interface QueuedBy {
+	principalId: string;
+}
+
+/**
+ * What cancelling or editing a queued message came to. `unknown`: none is queued under that id,
+ * such as one whose turn has started, been cancelled, or been steered into the running turn.
+ * `forbidden`: it is queued, but not by that principal. `refused` (edit only): the claim would no
+ * longer take the message with the new text.
+ */
+export type QueuedChange = "done" | "unknown" | "forbidden" | "refused";
+
 /** How a turn nobody wrote in the channel ended. */
 export type ScheduledOutcome =
 	| { status: "ran" }
@@ -205,8 +230,8 @@ export type Admission =
 			run(): Promise<void>;
 			/**
 			 * Called instead of `run` when the router drops the message the claim admitted, because
-			 * its author, once recorded, was not who they were when admitted; frees what the claim
-			 * holds for it.
+			 * its author, once recorded, was not who they were when admitted, or because it was
+			 * cancelled or replaced by an edit while it waited; frees what the claim holds for it.
 			 */
 			dropped?(): void;
 			/** The log line when the turn throws. */
@@ -327,6 +352,34 @@ export interface ConversationPort {
 	): Promise<void>;
 	/** Tells the claim that owns the channel a message was edited (`ChannelClaim.onMessageEdited`); never rejects. */
 	messageEdited?(message: InboundMessage): Promise<void>;
+	/**
+	 * The messages waiting in the channel for their own turn, oldest first: a message sent during
+	 * a turn that the running turn did not take (`QUEUED_MARK`). One that started, was steered
+	 * into the running turn, or was cancelled is not listed. Optional so a port written before 0.28
+	 * still type-checks; the host's has it.
+	 */
+	queued?(channel: ChannelKey): readonly QueuedMessage[];
+	/**
+	 * Cancels a queued message so its turn never starts, for its author only. `unknown` once the
+	 * turn has started, so a caller can tell the person it is too late. The surface is told only
+	 * through the message's `QUEUED_MARK` being removed.
+	 */
+	cancelQueued?(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy,
+	): QueuedChange;
+	/**
+	 * Replaces the text a queued message's turn will use, for its author only: the claim that
+	 * admitted the message admits it again with the new text, and the turn runs on that. The
+	 * surface's own copy of the message is the caller's to change.
+	 */
+	editQueued?(
+		channel: ChannelKey,
+		messageId: string,
+		by: QueuedBy,
+		text: string,
+	): QueuedChange;
 }
 
 /**

package/src/core/discord/direct-channel.ts

@@ -36,6 +36,7 @@ export function discordDirectChannel(
 	};
 	return {
 		name: "discord",
+		surface: "discord",
 		label: "a direct message on Discord",
 		knows: async (principalId) => (await userOf(principalId)) !== undefined,
 		reaches: async (principalId) => {

package/src/core/host-registration.ts

@@ -274,6 +274,10 @@ export class Linkage {
 			messageDeleted: (channel, id, space) =>
 				router().messageDeleted(channel, id, space),
 			messageEdited: (message) => router().messageEdited(message),
+			queued: (channel) => router().queued(channel),
+			cancelQueued: (channel, id, by) => router().cancelQueued(channel, id, by),
+			editQueued: (channel, id, by, text) =>
+				router().editQueued(channel, id, by, text),
 			background: (turn) => router().background(turn),
 			runsAs: (turn) => router().runsAs(turn),
 			target: (name) => router().target(name),

package/src/core/modules/notify/notify.ts

@@ -19,7 +19,8 @@ export interface SessionNotify {
 
 /**
  * Registers notify for one session: it sends a notice to the person the conversation serves,
- * through the first direct channel that reaches them, and refuses when none does. Its 0.8 name,
+ * through the direct channel on the conversation's own surface (another only when that one cannot
+ * reach them), and refuses when none does. Its 0.8 name,
  * `notify_owner`, still names it in a selection and in `toolTiers` until 1.0 (`RENAMED_TOOLS`).
  */
 export function notifyExtension(
@@ -37,7 +38,7 @@ export function notifyExtension(
 		return {
 			name: "notify",
 			label: "Notify",
-			description: `Send ${o.name} ${notify.channels}. Use only when ${o.he} asks to be notified or reminded by DM; your normal reply already reaches ${o.him}.`,
+			description: `Send ${o.name} ${notify.channels}. It goes out on this conversation's own surface. Use only when ${o.he} asks to be notified or reminded; your normal reply already reaches ${o.him}.`,
 			parameters: Type.Object({
 				text: Type.String({ description: "The message to send." }),
 			}),

package/src/core/modules/notify/session-notify.ts

@@ -1,7 +1,9 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { ChannelKey } from "../../domain/conversation.ts";
 import { SYSTEM_PRINCIPAL } from "../../identity/principal-store.ts";
 import type { OwnerIdentity } from "../../identity.ts";
 import type { Logger } from "../../log.ts";
+import { providerSurface, surfaceOf } from "../../presence/delivery-router.ts";
 import type {
 	DirectChannelProvider,
 	DirectChannels,
@@ -26,10 +28,21 @@ function labels(providers: readonly DirectChannelProvider[]): string {
 	return providers.map((provider) => provider.label).join(" or ");
 }
 
+/** The providers on the conversation's own surface, or every one when none is on it. */
+function ownSurface(
+	providers: readonly DirectChannelProvider[],
+	home: ChannelKey,
+): readonly DirectChannelProvider[] {
+	const surface = surfaceOf(home);
+	const own = providers.filter((p) => providerSurface(p) === surface);
+	return own.length > 0 ? own : providers;
+}
+
 /**
  * The notify tool of each session: none on a host without direct channels, and none in a private
  * conversation whose person no direct channel reaches. A notice goes to the conversation's
- * person in a private one, and to the turn's speaker in a shared one.
+ * person in a private one, and to the turn's speaker in a shared one, on the conversation's own
+ * surface: the delivery router tries another only when that one cannot reach them.
  */
 export function sessionNotify(
 	deps: SessionNotifyDeps,
@@ -70,15 +83,16 @@ export function sessionNotify(
 		const providers = directChannels.providers();
 		if (providers.length === 0) return null;
 		const { conversation } = session;
+		const origin = session.homeChannel;
 		const own =
 			conversation.visibility === "private"
 				? conversation.principalId
 				: undefined;
 		return async (pi) => {
-			let reaching = providers;
+			let reaching = ownSurface(providers, origin);
 			if (own !== undefined) {
 				try {
-					const known = await directChannels.known(own);
+					const known = await directChannels.known(origin, own);
 					if (!known) return;
 					reaching = [known];
 				} catch (error) {
@@ -98,7 +112,10 @@ export function sessionNotify(
 					: session.addressee;
 			await notifyExtension(
 				{
-					notifier: directChannels,
+					notifier: {
+						notify: (principalId, text) =>
+							directChannels.notify(origin, principalId, text),
+					},
 					recipient: async () => recipientOf(session, own),
 					channels: labels(reaching),
 				},

package/src/core/modules/skills/skill-contract.ts

@@ -4,6 +4,7 @@ import type {
 	SkillSet,
 	SkillVersion,
 } from "./skill-rules.ts";
+import type { SkillGroup } from "./skill-store.ts";
 
 /** The skills agents carry: built in, linked from repositories, or written by an agent. */
 export interface SkillRegistry {
@@ -45,6 +46,16 @@ export interface SkillRegistry {
 	delete(name: string): Promise<string>;
 	/** The saved versions of an agent-written skill, newest first; none for any other skill. */
 	documentHistory(name: string): Promise<SkillVersion[]>;
+	/** Every skill group, by name: a named list of skills to filter by or apply to an agent once; an agent carries skills, not groups. */
+	groups(): SkillGroup[];
+	/** Creates or replaces a group; returns what it did. Throws AgentError for a refused name, an empty description or an unknown skill. */
+	setGroup(
+		name: string,
+		description: string,
+		skills: readonly string[],
+	): Promise<string>;
+	/** Deletes a group and leaves its skills and their carriers as they are; returns what it did. Throws AgentError for an unknown group. */
+	deleteGroup(name: string): Promise<string>;
 	/** Adds and removes an agent's registered skills together, or changes nothing; returns what it carries after. */
 	attach(
 		agent: string,

package/src/core/modules/skills/skill-registry.ts

@@ -28,7 +28,7 @@ import {
 	type SkillVersion,
 	skillFileContent,
 } from "./skill-rules.ts";
-import type { SkillEntry } from "./skill-store.ts";
+import type { SkillEntry, SkillGroup } from "./skill-store.ts";
 
 export {
 	BUILTIN_SKILLS,
@@ -343,6 +343,8 @@ export class StoredSkillRegistry implements SkillRegistry {
 		return this.#removed(name, detached);
 	}
 
+	readonly groups = (): SkillGroup[] => this.#options.store.groups();
+
 	async setGroup(
 		name: string,
 		description: string,

package/src/core/modules/skills/skill-store.ts

@@ -209,10 +209,11 @@ export class SkillStore {
 		return this.#skills.get(name);
 	}
 
+	/** Copies, by name, so a caller's change reaches no stored group. */
 	groups(): SkillGroup[] {
-		return [...this.#groups.values()].sort((a, b) =>
-			a.name.localeCompare(b.name),
-		);
+		return [...this.#groups.values()]
+			.map((group) => ({ ...group, skills: [...group.skills] }))
+			.sort((a, b) => a.name.localeCompare(b.name));
 	}
 
 	group(name: string): SkillGroup | undefined {

package/src/core/presence/delivery-router.ts

@@ -0,0 +1,165 @@
+import type { SurfacePort } from "../contract/surface.ts";
+import { parseChannelKey } from "../contract/surface.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { Logger } from "../log.ts";
+import { splitReply } from "../presentation/reply-splitter.ts";
+import type {
+	DirectChannelProvider,
+	DirectChannels,
+	DirectReach,
+} from "./direct-channels.ts";
+
+/**
+ * The conversation a piece of work came from: a turn's channel, a schedule's, a job's. Its surface
+ * is the key's prefix, and everything the work sends goes there, or to the same person on that
+ * surface, before any other.
+ */
+export type Origin = ChannelKey;
+
+/** The surface an origin is on: the prefix of its key, such as `discord` or `app`. */
+export function surfaceOf(origin: Origin): string {
+	return parseChannelKey(origin).surface;
+}
+
+/** The surface whose conversations a provider reaches: its `surface`, else its name. */
+export function providerSurface(provider: DirectChannelProvider): string {
+	return provider.surface ?? provider.name;
+}
+
+/**
+ * The one place that decides where a notice or run for a person goes, from the origin of the work.
+ * A provider on the origin's surface is tried first; another surface is tried only when none there
+ * reaches the person, and that fallback is logged with both surfaces. Mirroring is the provider's
+ * own: after a delivery, each other provider that declares `mirror` echoes the notice to the same
+ * person. Nothing here picks the "first" provider or the "most recent" conversation.
+ */
+export interface DeliveryRouter {
+	/** The providers in the order an origin tries them: its own surface's, then the rest. */
+	order(origin: Origin): readonly DirectChannelProvider[];
+	/** The person's own conversation for work from `origin`; undefined when no provider reaches them. */
+	reach(origin: Origin, principalId: string): Promise<DirectReach | undefined>;
+	/** The provider that knows the person for `origin`, without the network where it can tell. */
+	known(
+		origin: Origin,
+		principalId: string,
+	): Promise<DirectChannelProvider | undefined>;
+	/** Sends the person `text` for work from `origin`; false when no provider reaches them. */
+	notify(origin: Origin, principalId: string, text: string): Promise<boolean>;
+}
+
+export function deliveryRouter(
+	providers: () => readonly DirectChannelProvider[],
+	surfaces: Pick<SurfacePort, "sendReply">,
+	logger?: Pick<Logger, "warn">,
+): DeliveryRouter {
+	const order = (origin: Origin): readonly DirectChannelProvider[] => {
+		const surface = surfaceOf(origin);
+		const all = providers();
+		return [
+			...all.filter((p) => providerSurface(p) === surface),
+			...all.filter((p) => providerSurface(p) !== surface),
+		];
+	};
+	const fellBack = (
+		origin: Origin,
+		provider: DirectChannelProvider,
+		principalId: string,
+	): void => {
+		const from = surfaceOf(origin);
+		const to = providerSurface(provider);
+		if (from !== to)
+			logger?.warn(
+				{ origin, from, to, principalId, provider: provider.name },
+				"the origin's surface cannot reach the person; delivered on another surface",
+			);
+	};
+	const reach = async (
+		origin: Origin,
+		principalId: string,
+	): Promise<DirectReach | undefined> => {
+		for (const provider of order(origin)) {
+			const channel = await provider.reaches(principalId);
+			if (channel === undefined) continue;
+			fellBack(origin, provider, principalId);
+			return { provider, channel };
+		}
+		return undefined;
+	};
+	const mirrored = async (
+		delivered: DirectChannelProvider,
+		principalId: string,
+		text: string,
+	): Promise<void> => {
+		await Promise.all(
+			providers()
+				.filter((provider) => provider !== delivered && provider.mirror)
+				.map(async (provider) => {
+					try {
+						await provider.mirror?.(principalId, text);
+					} catch (error) {
+						logger?.warn(
+							{ err: error, provider: provider.name },
+							"a direct channel did not mirror a notice",
+						);
+					}
+				}),
+		);
+	};
+	return {
+		order,
+		reach,
+		known: async (origin, principalId) => {
+			for (const provider of order(origin)) {
+				const knows = provider.knows
+					? await provider.knows(principalId)
+					: (await provider.reaches(principalId)) !== undefined;
+				if (knows) return provider;
+			}
+			return undefined;
+		},
+		notify: async (origin, principalId, text) => {
+			const reached = await reach(origin, principalId);
+			if (!reached) return false;
+			if (reached.provider.deliver)
+				await reached.provider.deliver(principalId, text);
+			else
+				await surfaces.sendReply(reached.channel, {
+					chunks: splitReply(text),
+				});
+			await mirrored(reached.provider, principalId, text);
+			return true;
+		},
+	};
+}
+
+/** What `runChannelFor` reads: the surfaces, the direct channels, and which claims take background turns. */
+export interface RunChannelDeps {
+	surfaces: Pick<SurfacePort, "of">;
+	directChannels: Pick<DirectChannels, "reach">;
+	takesBackground(channel: ChannelKey): boolean;
+}
+
+/**
+ * The conversation a schedule's runs or a delegated job's report post in, for work created in
+ * `origin`: the origin itself when a chat surface carries it; otherwise the creator's own
+ * conversation the router reaches from that origin, which a claim must take background turns in.
+ * Throws `refused` with why there is none.
+ */
+export async function runChannelFor(
+	deps: RunChannelDeps,
+	origin: Origin,
+	principalId: string,
+	refused: (message: string) => Error,
+): Promise<ChannelKey> {
+	if (deps.surfaces.of(origin)) return origin;
+	const reached = await deps.directChannels.reach(origin, principalId);
+	if (!reached)
+		throw refused(
+			"this conversation has no chat surface to post a run in, and you have no direct channel on this host to post it in instead",
+		);
+	if (!deps.takesBackground(reached.channel))
+		throw refused(
+			`this conversation has no chat surface to post a run in, and nothing here takes background turns in your ${reached.provider.name} direct messages, where it would go instead`,
+		);
+	return reached.channel;
+}