pi-roundtable 0.27.1 → 0.29.0

package/src/core/modes/conversation-modes.ts

@@ -5,6 +5,12 @@ import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
 import type { Logger } from "../log.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
+import {
+	followersOf,
+	type ModeOrigins,
+	resolveMode,
+	type StoredMode,
+} from "./mode-inheritance.ts";
 
 /** What a conversation is set to run unattended: both off until an owner switches them on. */
 export interface ConversationMode {
@@ -15,6 +21,12 @@ export interface ConversationMode {
 	/** The principal who last changed it; absent for a conversation never changed. */
 	changedBy?: string;
 	changedAt?: Date;
+	/**
+	 * Present when the modes follow another conversation's, live: a temp knight's follow the
+	 * conversation it was made from. `name` is that conversation's, as the agent server tells it;
+	 * `gone` says it no longer exists, so both modes are off. `set` refuses such a conversation.
+	 */
+	inheritedFrom?: { channel: ChannelKey; name?: string; gone?: true };
 }
 
 /** Which modes a change sets; a mode left out stays as it is. */
@@ -53,7 +65,33 @@ export interface ConversationModes {
 		change: ModeChange,
 		by: Speaker,
 	): Promise<ConversationMode>;
-	/** Called after each change. Returns the function that stops it. A throwing listener is logged. */
+	/**
+	 * Makes each of `channels` follow `origin`'s modes live, in place of its own: `peek` returns the
+	 * origin's, with `inheritedFrom`, and `set` is refused for it. Stored, so it survives a restart.
+	 * Throws `PluginError` unless `by` is an owner other than the system principal, as `set` does.
+	 */
+	follow(
+		channels: readonly ChannelKey[],
+		origin: ChannelKey,
+		by: Speaker,
+	): Promise<void>;
+	/**
+	 * Drops a conversation's modes and what it follows, as for a conversation that is gone or made
+	 * anew. It only turns modes off, so it needs no speaker.
+	 */
+	forget(channel: ChannelKey): Promise<void>;
+	/**
+	 * How a following conversation's origin is named and whether it still exists; the agent server
+	 * gives it. `originOf` is undefined when `channel` no longer follows `origin`, so its own modes
+	 * count again; `alive: false` when the origin is gone, so both modes read off.
+	 */
+	trackOrigins(origins: {
+		originOf(
+			channel: ChannelKey,
+			origin: ChannelKey,
+		): { name: string; alive: boolean } | undefined;
+	}): void;
+	/** Called after each change, also for each conversation that follows the changed one. Returns the function that stops it. A throwing listener is logged. */
 	onChange(
 		listener: (channel: ChannelKey, mode: ConversationMode) => void,
 	): () => void;
@@ -68,27 +106,35 @@ interface Row {
 	long_running: boolean;
 	changed_by: string | null;
 	changed_at: Date;
+	follows: string | null;
 }
 
-const OFF: ConversationMode = Object.freeze({
-	yolo: false,
-	longRunning: false,
-});
-
-function modeOf(row: Row): ConversationMode {
-	return Object.freeze({
-		yolo: row.yolo,
-		longRunning: row.long_running,
-		...(row.changed_by === null ? {} : { changedBy: row.changed_by }),
-		changedAt: row.changed_at,
-	});
+function storedOf(row: Row): StoredMode {
+	return {
+		own: Object.freeze({
+			yolo: row.yolo,
+			longRunning: row.long_running,
+			...(row.changed_by === null ? {} : { changedBy: row.changed_by }),
+			changedAt: row.changed_at,
+		}),
+		...(row.follows === null ? {} : { follows: row.follows as ChannelKey }),
+	};
+}
+
+/** Refuses a change of modes by anyone but an owner, and by the host's own turns. */
+function checkOwner(by: Speaker): void {
+	if (by.tier !== "owner" || by.principalId === SYSTEM_PRINCIPAL)
+		throw new PluginError(
+			"only an owner sets a conversation's modes, and not the host's own turns",
+		);
 }
 
 /** The conversation modes in the `conversation_modes` table, cached in memory after one load. */
 export class PgConversationModes implements ConversationModes {
 	readonly #sql: SQL;
 	readonly #logger: Logger;
-	readonly #modes = new Map<ChannelKey, ConversationMode>();
+	readonly #modes = new Map<ChannelKey, StoredMode>();
+	#origins: ModeOrigins | undefined;
 	readonly #changed = new Set<
 		(channel: ChannelKey, mode: ConversationMode) => void
 	>();
@@ -99,7 +145,7 @@ export class PgConversationModes implements ConversationModes {
 		this.#logger = logger;
 	}
 
-	/** The modes' table; the host runs this before the modes attach. */
+	/** The modes' table; the host runs this, then `followsMigration`, before the modes attach. */
 	static readonly migration: Migration = {
 		name: "conversation-modes",
 		up: async (sql) => {
@@ -114,6 +160,20 @@ export class PgConversationModes implements ConversationModes {
 		},
 	};
 
+	/** The conversation whose modes a row follows, such as a temp knight's origin. */
+	static readonly followsMigration: Migration = {
+		name: "conversation-modes-follows",
+		up: async (sql) => {
+			await sql`ALTER TABLE conversation_modes ADD COLUMN IF NOT EXISTS follows text`;
+		},
+	};
+
+	/** Every migration of the modes' table, in order. */
+	static readonly migrations: readonly Migration[] = [
+		PgConversationModes.migration,
+		PgConversationModes.followsMigration,
+	];
+
 	/**
 	 * The modes over the host's migrated pool, with none loaded: `Roundtable.check()` opens no
 	 * connection, so the rows are read by `load`, from the plugin's service start.
@@ -128,11 +188,15 @@ export class PgConversationModes implements ConversationModes {
 		// A mode `set` wrote while the rows were read is newer than its row here.
 		for (const row of rows)
 			if (!this.#modes.has(row.channel as ChannelKey))
-				this.#modes.set(row.channel as ChannelKey, modeOf(row));
+				this.#modes.set(row.channel as ChannelKey, storedOf(row));
 	}
 
 	peek(channel: ChannelKey): ConversationMode {
-		return this.#modes.get(channel) ?? OFF;
+		return resolveMode(channel, (key) => this.#modes.get(key), this.#origins);
+	}
+
+	trackOrigins(origins: ModeOrigins): void {
+		this.#origins = origins;
 	}
 
 	async set(
@@ -140,9 +204,11 @@ export class PgConversationModes implements ConversationModes {
 		change: ModeChange,
 		by: Speaker,
 	): Promise<ConversationMode> {
-		if (by.tier !== "owner" || by.principalId === SYSTEM_PRINCIPAL)
+		checkOwner(by);
+		const inherited = this.peek(channel).inheritedFrom;
+		if (inherited)
 			throw new PluginError(
-				"only an owner sets a conversation's modes, and not the host's own turns",
+				`this conversation follows the modes of ${inherited.name ?? inherited.channel}; change them there`,
 			);
 		const yolo = change.yolo ?? null;
 		const longRunning = change.longRunning ?? null;
@@ -155,13 +221,14 @@ export class PgConversationModes implements ConversationModes {
 				yolo = COALESCE(${yolo}::boolean, conversation_modes.yolo),
 				long_running = COALESCE(${longRunning}::boolean, conversation_modes.long_running),
 				changed_by = ${by.principalId},
-				changed_at = now()
+				changed_at = now(),
+				follows = NULL
 			RETURNING *`;
 		const [row] = rows;
 		if (!row)
 			throw new Error(`conversation modes of ${channel} were not stored`);
-		const mode = modeOf(row);
-		this.#modes.set(channel, mode);
+		this.#modes.set(channel, storedOf(row));
+		const mode = this.peek(channel);
 		this.#logger.info(
 			{
 				channel,
@@ -171,10 +238,44 @@ export class PgConversationModes implements ConversationModes {
 			},
 			"conversation modes changed",
 		);
-		this.#tell(this.#changed, "change", (listener) => listener(channel, mode));
+		this.#announce(channel);
 		return mode;
 	}
 
+	async follow(
+		channels: readonly ChannelKey[],
+		origin: ChannelKey,
+		by: Speaker,
+	): Promise<void> {
+		checkOwner(by);
+		for (const channel of channels) {
+			// Its own modes go off: they count again only once it no longer follows.
+			const rows: Row[] = await this.#sql`
+				INSERT INTO conversation_modes (channel, yolo, long_running, changed_by, changed_at, follows)
+				VALUES (${channel}, false, false, ${by.principalId}, now(), ${origin})
+				ON CONFLICT (channel) DO UPDATE SET
+					yolo = false, long_running = false, changed_by = ${by.principalId},
+					changed_at = now(), follows = ${origin}
+				RETURNING *`;
+			const [row] = rows;
+			if (!row)
+				throw new Error(`conversation modes of ${channel} were not stored`);
+			this.#modes.set(channel, storedOf(row));
+			this.#logger.info(
+				{ channel, origin, by: by.principalId },
+				"conversation modes follow another conversation",
+			);
+			this.#announce(channel);
+		}
+	}
+
+	async forget(channel: ChannelKey): Promise<void> {
+		await this.#sql`DELETE FROM conversation_modes WHERE channel = ${channel}`;
+		if (!this.#modes.delete(channel)) return;
+		this.#logger.info({ channel }, "conversation modes forgotten");
+		this.#announce(channel);
+	}
+
 	onChange(
 		listener: (channel: ChannelKey, mode: ConversationMode) => void,
 	): () => void {
@@ -200,6 +301,17 @@ export class PgConversationModes implements ConversationModes {
 		return () => void this.#approved.delete(listener);
 	}
 
+	/** Tells the listeners of `channel`'s modes, and of each conversation that follows it. */
+	#announce(channel: ChannelKey): void {
+		for (const key of [
+			channel,
+			...followersOf(channel, this.#modes, this.#origins),
+		]) {
+			const mode = this.peek(key);
+			this.#tell(this.#changed, "change", (listener) => listener(key, mode));
+		}
+	}
+
 	/** Runs each listener; one that throws is logged and the rest still hear it. */
 	#tell<L>(listeners: Set<L>, what: string, call: (listener: L) => void): void {
 		for (const listener of [...listeners]) {

package/src/core/modes/mode-inheritance.ts

@@ -0,0 +1,78 @@
+import type { ChannelKey } from "../sessions.ts";
+import type { ConversationMode } from "./conversation-modes.ts";
+
+/**
+ * What the agent server says of a conversation that follows another's modes, given to
+ * `ConversationModes.trackOrigins`.
+ */
+export interface ModeOrigins {
+	/**
+	 * Whether `channel` still follows `origin`, as a temp knight's conversation follows the one it
+	 * was made from, and the origin's name to show: undefined when it no longer does (its agent is
+	 * gone, or the name is another agent's now), so its own modes count again; `alive: false` when
+	 * the origin conversation is gone, so both modes read off.
+	 */
+	originOf(
+		channel: ChannelKey,
+		origin: ChannelKey,
+	): { name: string; alive: boolean } | undefined;
+}
+
+/** A conversation's stored modes, and the conversation it follows when it follows one. */
+export interface StoredMode {
+	own: ConversationMode;
+	follows?: ChannelKey;
+}
+
+const OFF: ConversationMode = Object.freeze({
+	yolo: false,
+	longRunning: false,
+});
+
+/**
+ * A conversation's modes as they apply now: its own, or, for one that follows another, the
+ * origin's own modes with `inheritedFrom`, both off when the origin is gone. One level only: an
+ * origin's modes are its own, whatever it follows. Without `origins` an origin counts as alive.
+ */
+export function resolveMode(
+	channel: ChannelKey,
+	stored: (channel: ChannelKey) => StoredMode | undefined,
+	origins: ModeOrigins | undefined,
+): ConversationMode {
+	const mine = stored(channel);
+	if (!mine) return OFF;
+	const follows = mine.follows;
+	if (follows === undefined) return mine.own;
+	const origin = origins
+		? origins.originOf(channel, follows)
+		: { name: undefined, alive: true };
+	if (!origin) return mine.own;
+	const from = origin.alive ? (stored(follows)?.own ?? OFF) : OFF;
+	return Object.freeze({
+		yolo: from.yolo,
+		longRunning: from.longRunning,
+		...(from.changedBy === undefined ? {} : { changedBy: from.changedBy }),
+		...(from.changedAt === undefined ? {} : { changedAt: from.changedAt }),
+		inheritedFrom: {
+			channel: follows,
+			...(origin.name === undefined ? {} : { name: origin.name }),
+			...(origin.alive ? {} : { gone: true as const }),
+		},
+	});
+}
+
+/** The conversations that follow `origin` now, from every stored one. */
+export function followersOf(
+	origin: ChannelKey,
+	all: Iterable<[ChannelKey, StoredMode]>,
+	origins: ModeOrigins | undefined,
+): ChannelKey[] {
+	const found: ChannelKey[] = [];
+	for (const [channel, mode] of all)
+		if (
+			mode.follows === origin &&
+			(!origins || origins.originOf(channel, origin) !== undefined)
+		)
+			found.push(channel);
+	return found;
+}

package/src/core/modes/modes-plugin.ts

@@ -13,7 +13,7 @@ export const MODES_PLUGIN = "modes";
 export function modesPlugin(): RoundtablePlugin {
 	return {
 		name: MODES_PLUGIN,
-		migrations: [PgConversationModes.migration],
+		migrations: [...PgConversationModes.migrations],
 		provides: [MODES],
 		setup: ({ database, logger, services }) => {
 			const modes = PgConversationModes.attach(database(), logger);

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 {
@@ -41,8 +42,20 @@ export interface SkillRegistry {
 	): Promise<SkillDocument>;
 	/** Makes a skill from a whole SKILL.md, as `skill_create` does; it is attached to no one. Throws AgentError for a taken or refused name or text. */
 	createDocument(text: string, by: string): Promise<SkillDocument>;
+	/** Deletes an agent-written skill and detaches it from every agent and group, as `skill_delete` does; returns what it was detached from. Throws AgentError for any other skill. */
+	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;
+}