pi-roundtable 0.8.0 → 0.9.0

package/src/core/modules/schedules/schedule-tools.ts

@@ -3,6 +3,7 @@ import type { ChannelKey } from "../../domain/conversation.ts";
 import { ScheduleError } from "../../domain/errors.ts";
 import type { HoldCheck } from "../../holds.ts";
 import { messages } from "../../i18n/index.ts";
+import { SYSTEM_PRINCIPAL } from "../../identity/principal-store.ts";
 import type { ScheduleStore } from "../../services.ts";
 import type { ScheduleToolName } from "../../shared/schedule-tools.ts";
 import { type Tier, tierAtLeast } from "../../speakers.ts";
@@ -20,7 +21,7 @@ import {
 	type Recurrence,
 	type RecurrenceInput,
 } from "./recurrence.ts";
-import type { Schedule } from "./schedule-store.ts";
+import type { NewSchedule, Schedule } from "./schedule-store.ts";
 
 const TITLE_CHARS = 80;
 const LIST_PROMPT_PREVIEW = 200;
@@ -29,16 +30,35 @@ const DESCRIBE_TIMEOUT_MS = 10_000;
 const DAY_MS = 86_400_000;
 
 export interface ScheduleToolContext {
+	/**
+	 * The schedules; `all` and `createWithin` are needed only where the target counts each person's
+	 * (`perPrincipal`).
+	 */
 	store: Pick<
 		ScheduleStore,
 		"create" | "get" | "forChannel" | "update" | "remove"
-	>;
+	> &
+		Partial<Pick<ScheduleStore, "all" | "createWithin">>;
 	channel: ChannelKey;
 	/** Whose schedules these are; its `schedules` limits apply, and without them nothing is scheduled. */
 	target: BackgroundTarget;
-	/** Who asked, recorded on created schedules; a scheduled run speaks for its creator. */
-	author: { id: string; name: string; tier?: Tier };
+	/**
+	 * Who asked: their principal, recorded as a created schedule's creator, the name it lists, and
+	 * the tier its runs ask for; a scheduled run speaks for its creator. The host's own turns,
+	 * whose principal is the system's, create none.
+	 */
+	author: { principalId: string; id: string; name: string; tier: Tier };
 	now: Date;
+	/**
+	 * Whose the conversation is: in a `private` one the asker lists, reads, changes, and cancels
+	 * only their own schedules; in a `shared` one, the default, every schedule of the channel.
+	 */
+	visibility?: "private" | "shared";
+	/**
+	 * The principal a schedule's creator id stands for, such as the primary owner for 0.8's
+	 * `remote-mcp`; without it, or when it knows none, the id is the principal's.
+	 */
+	principalOf?: (createdById: string) => Promise<string | undefined>;
 	/**
 	 * The host's prechecks a schedule may name, and the runner of the scripts it may carry instead;
 	 * without them, none can be attached.
@@ -160,7 +180,7 @@ async function precheckCatalog(ctx: ScheduleToolContext): Promise<string> {
 			runner.describe({
 				channel: ctx.channel,
 				target: ctx.target.name,
-				...(ctx.author.tier ? { tier: ctx.author.tier } : {}),
+				tier: ctx.author.tier,
 			}),
 		)
 		.then(
@@ -221,24 +241,109 @@ function line(schedule: Schedule): string {
 	return `- #${schedule.id} ${schedule.title}: ${describeRecurrence(schedule.recurrence)}, next ${zonedStamp(schedule.nextRun)}; set by ${schedule.createdByName}${precheck}${last}\n  ${prompt.replace(/\n/g, " ")}`;
 }
 
+/** The principal who created a schedule. */
+async function creatorOf(
+	ctx: ScheduleToolContext,
+	schedule: Schedule,
+): Promise<string> {
+	return (
+		(await ctx.principalOf?.(schedule.createdById)) ?? schedule.createdById
+	);
+}
+
+/** Whether the asker sees a schedule of the channel: in a private conversation only their own. */
+async function visible(
+	ctx: ScheduleToolContext,
+	schedule: Schedule,
+): Promise<boolean> {
+	return (
+		ctx.visibility !== "private" ||
+		(await creatorOf(ctx, schedule)) === ctx.author.principalId
+	);
+}
+
 async function own(ctx: ScheduleToolContext, input: Input): Promise<Schedule> {
 	const schedule = await ctx.store.get(id(input));
-	if (!schedule || schedule.channel !== ctx.channel)
+	if (
+		!schedule ||
+		schedule.channel !== ctx.channel ||
+		!(await visible(ctx, schedule))
+	)
 		throw new ScheduleError(
 			`this channel has no schedule #${String(input.id)}`,
 		);
 	return schedule;
 }
 
+/**
+ * The creator ids that stand for the asker among the target's schedules, for a target that counts
+ * each person's (`perPrincipal`): their principal's and any older id read as theirs, such as 0.8's
+ * `remote-mcp` for the primary owner. Undefined for a target that counts per conversation only.
+ */
+async function perPrincipalCreators(
+	ctx: ScheduleToolContext,
+): Promise<string[] | undefined> {
+	const { perPrincipal } = limitsOf(ctx);
+	if (perPrincipal === undefined) return undefined;
+	if (!ctx.store.all || !ctx.store.createWithin)
+		throw new ScheduleError(
+			`${ctx.target.name} schedules are counted per person, and this host's schedule store cannot count them`,
+		);
+	const creators = new Set([ctx.author.principalId]);
+	for (const schedule of await ctx.store.all())
+		if (
+			schedule.target === ctx.target.name &&
+			!creators.has(schedule.createdById) &&
+			(await creatorOf(ctx, schedule)) === ctx.author.principalId
+		)
+			creators.add(schedule.createdById);
+	return [...creators];
+}
+
+/**
+ * Stores a new schedule, within the target's limit of one person's across all their conversations
+ * where it has one: counted and stored under a lock on the person, so creates at once stay within it.
+ */
+async function created(
+	ctx: ScheduleToolContext,
+	schedule: NewSchedule,
+): Promise<Schedule> {
+	const creators = await perPrincipalCreators(ctx);
+	const { perPrincipal } = limitsOf(ctx);
+	if (!creators || perPrincipal === undefined || !ctx.store.createWithin)
+		return ctx.store.create(schedule);
+	const outcome = await ctx.store.createWithin(schedule, {
+		creators,
+		max: perPrincipal,
+	});
+	if ("reached" in outcome)
+		throw new ScheduleError(
+			`you already have ${outcome.reached} schedules, the most one person may have here; cancel one first`,
+		);
+	return outcome.created;
+}
+
 /** A schedule runs at its creator's tier, so someone of a lower tier may not rewrite it. */
 function changeable(ctx: ScheduleToolContext, schedule: Schedule): Schedule {
-	if (ctx.author.tier && !tierAtLeast(ctx.author.tier, schedule.createdTier))
+	if (!tierAtLeast(ctx.author.tier, schedule.createdTier))
 		throw new ScheduleError(
 			`schedule #${schedule.id} was set by a higher tier; only that tier or above can change it`,
 		);
 	return schedule;
 }
 
+/**
+ * The host's own turns, such as a logged error's or an outside webhook's report, read text no one
+ * vouches for, so they leave no schedule behind them that runs later as someone's: they may only
+ * list schedules.
+ */
+function notTheHost(ctx: ScheduleToolContext, refusal: string): void {
+	if (ctx.author.principalId === SYSTEM_PRINCIPAL)
+		throw new ScheduleError(
+			`the host's own turns, such as a report's, ${refusal}`,
+		);
+}
+
 /** Runs one schedule tool against the channel's schedules and returns the answer for the model. */
 export async function callScheduleTool(
 	ctx: ScheduleToolContext,
@@ -249,6 +354,7 @@ export async function callScheduleTool(
 	const limits = limitsOf(ctx);
 	switch (name) {
 		case "schedule_create": {
+			notTheHost(ctx, "set up no schedules; ask the owner to set it up");
 			const title = text(input, "title", TITLE_CHARS);
 			const prompt = text(input, "prompt", limits.promptChars);
 			const [recurrence, next] = timing(ctx, input);
@@ -267,16 +373,16 @@ export async function callScheduleTool(
 				throw new ScheduleError(
 					`this channel already has ${existing.length} schedules, the most it may have; cancel one first`,
 				);
-			const created = await ctx.store.create({
+			const made = await created(ctx, {
 				channel: ctx.channel,
 				target: ctx.target.name,
 				title,
 				prompt,
 				recurrence,
 				nextRun: next,
-				createdById: ctx.author.id,
+				createdById: ctx.author.principalId,
 				createdByName: ctx.author.name,
-				createdTier: ctx.author.tier ?? "owner",
+				createdTier: ctx.author.tier,
 				...(precheck ? { precheck } : {}),
 				...(script
 					? { precheckScript: script.script, precheckTools: script.tools }
@@ -287,7 +393,7 @@ export async function callScheduleTool(
 				: script
 					? "; its precheck script runs first"
 					: "";
-			return `Scheduled #${created.id} "${title}": ${describeRecurrence(recurrence)}, first run ${zonedStamp(next)} ${messages().zoneTime(timeZone())}${checked}.`;
+			return `Scheduled #${made.id} "${title}": ${describeRecurrence(recurrence)}, first run ${zonedStamp(next)} ${messages().zoneTime(timeZone())}${checked}.`;
 		}
 		case "schedule_list": {
 			if (input.id !== undefined) {
@@ -297,7 +403,9 @@ export async function callScheduleTool(
 					: "";
 				return `${line(schedule).split("\n")[0]}\n\nPrompt:\n${schedule.prompt}${script}`;
 			}
-			const all = await ctx.store.forChannel(ctx.channel);
+			const all: Schedule[] = [];
+			for (const schedule of await ctx.store.forChannel(ctx.channel))
+				if (await visible(ctx, schedule)) all.push(schedule);
 			const listed =
 				all.length === 0
 					? "This channel has no schedules."
@@ -305,6 +413,7 @@ export async function callScheduleTool(
 			return `${listed}${await precheckCatalog(ctx)}`;
 		}
 		case "schedule_update": {
+			notTheHost(ctx, "change no schedules; ask the owner to change it");
 			const schedule = changeable(ctx, await own(ctx, input));
 			const change: Parameters<ScheduleToolContext["store"]["update"]>[2] = {};
 			if (input.title !== undefined)
@@ -349,6 +458,7 @@ export async function callScheduleTool(
 			return `Updated #${updated.id} "${updated.title}": ${describeRecurrence(updated.recurrence)}, next run ${zonedStamp(updated.nextRun)}${checked}.`;
 		}
 		case "schedule_cancel": {
+			notTheHost(ctx, "cancel no schedules; ask the owner to cancel it");
 			const schedule = changeable(ctx, await own(ctx, input));
 			await ctx.store.remove(schedule.id, ctx.channel);
 			return `Cancelled #${schedule.id} "${schedule.title}".`;

package/src/core/modules/schedules/scheduler.ts

@@ -1,4 +1,7 @@
-import type { ScheduledOutcome } from "../../contract/channels.ts";
+import type {
+	BackgroundRunsAs,
+	ScheduledOutcome,
+} from "../../contract/channels.ts";
 import type { HoldCheck } from "../../holds.ts";
 import type { Logger } from "../../log.ts";
 import type { ScheduleStore } from "../../services.ts";
@@ -20,6 +23,11 @@ export interface ScheduledRunner {
 		firedAt: Date,
 		finding?: PrecheckFinding,
 	): Promise<ScheduledOutcome>;
+	/**
+	 * Who the schedule's turn would run as now, asked before its precheck: a precheck runs only for
+	 * a creator who may run the turn, at the tier it would run at. Throws when that cannot be told.
+	 */
+	runsAs(schedule: Schedule): Promise<BackgroundRunsAs>;
 }
 
 /** How long stop waits for running prechecks to clean up after aborting them. */
@@ -169,7 +177,29 @@ export class Scheduler {
 			schedule.precheck ??
 			(schedule.precheckScript ? SCRIPT_PRECHECK : undefined);
 		if (name) {
-			const decision = await this.#prechecks.run(schedule, name, firedAt);
+			// A creator who may not run the turn now, such as one disabled, runs no precheck either.
+			const runs = await this.#runsAs(schedule);
+			if (this.#stopping.signal.aborted) {
+				await this.#record(
+					schedule,
+					"skipped: the host stopped before its run",
+				);
+				return;
+			}
+			if ("skipped" in runs) {
+				logger.info(
+					{ schedule: schedule.id, reason: runs.skipped },
+					"schedule skipped before its precheck",
+				);
+				await this.#record(schedule, `skipped: ${runs.skipped}`);
+				return;
+			}
+			const decision = await this.#prechecks.run(
+				schedule,
+				name,
+				firedAt,
+				runs.speaker.tier,
+			);
 			if (this.#stopping.signal.aborted) {
 				await this.#record(
 					schedule,
@@ -202,6 +232,17 @@ export class Scheduler {
 		);
 	}
 
+	/** Who the schedule runs as; a failure to tell is a reason to skip it, as its turn would not run. */
+	async #runsAs(schedule: Schedule): Promise<BackgroundRunsAs> {
+		try {
+			return await this.#options.runner.runsAs(schedule);
+		} catch (error) {
+			return {
+				skipped: `whom it runs as could not be checked (${error instanceof Error ? error.message : String(error)})`,
+			};
+		}
+	}
+
 	/** Records a run the precheck skipped and posts its note; a note that cannot be posted is logged. */
 	async #skip(schedule: Schedule, note: string | undefined): Promise<void> {
 		const { notify, logger } = this.#options;

package/src/core/modules/schedules/schedules.ts

@@ -1,11 +1,10 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { OWNER_TARGET } from "../../agents/agent-claim.ts";
+import type { BackgroundTarget } from "../../contract/channels.ts";
 import type { ChannelKey } from "../../domain/conversation.ts";
 import { ScheduleError } from "../../domain/errors.ts";
 import type { HoldCheck } from "../../holds.ts";
 import { activeLocale } from "../../i18n/index.ts";
-import type { OwnerIdentity } from "../../identity.ts";
 import {
 	type ToolInput,
 	textToolsExtension,
@@ -17,22 +16,32 @@ import {
 } from "../../shared/schedule-tools.ts";
 import type { Speaker } from "../../speakers.ts";
 import { timeZone } from "../../time.ts";
+import { PERSONAL_TARGET } from "../background/personal-target.ts";
 import type { PrecheckRegistry } from "./prechecks.ts";
 import { callScheduleTool } from "./schedule-tools.ts";
 
 export interface OwnerSchedules {
 	store: ScheduleStore;
-	owner: { id: string; name: string };
 	/**
-	 * The chat channel a conversation's schedules belong to: itself, or the owner's direct
-	 * messages for a conversation no chat surface carries, where a run could not be posted.
+	 * The chat channel a conversation's schedules belong to: itself, or, for a conversation no chat
+	 * surface carries, where a run could not be posted, the asker's direct messages; asked with the
+	 * asker's principal, and throws ScheduleError when their runs could go nowhere.
 	 */
-	channelFor: (channel: ChannelKey) => Promise<ChannelKey>;
+	channelFor: (channel: ChannelKey, principalId: string) => Promise<ChannelKey>;
 	/** The host's prechecks a schedule may name, and the runner of scripts it may carry; without them, none can be attached. */
 	prechecks?: Pick<PrecheckRegistry, "get" | "list"> &
 		Partial<Pick<PrecheckRegistry, "scriptRunner">>;
 	/** The host's hold rules, which mark a saved script's approved tools. */
 	holds?: () => HoldCheck;
+	/**
+	 * Whose the conversation is, read when a tool runs: in a private one the speaker sees only
+	 * their own schedules. Without it, every schedule of the channel, as in a shared one.
+	 */
+	visibility?: () => Promise<"private" | "shared">;
+	/** The principal a schedule's creator id stands for, such as the primary owner for 0.8's `remote-mcp`. */
+	principalOf?: (createdById: string) => Promise<string | undefined>;
+	/** The target the schedules are made for, with its limits; default `PERSONAL_TARGET`. */
+	target?: BackgroundTarget;
 }
 
 /** Finds another agent's channel, for reading its schedules; throws ScheduleError when there is none. */
@@ -54,18 +63,26 @@ function withAgentOption(spec: ScheduleToolSpec): ScheduleToolSpec {
 }
 
 /**
- * Registers the schedule tools for one owner conversation; its runs speak for the owner. With
- * `agents`, schedule_list can also read another agent's schedules.
+ * Registers the schedule tools for one conversation; a schedule's runs speak for the person whose
+ * turn set it up, and in a turn nobody is named for the tools refuse. With `agents`,
+ * schedule_list can also read another agent's schedules.
  */
 export function schedulesExtension(
 	schedules: OwnerSchedules,
 	channel: ChannelKey,
-	identity: OwnerIdentity,
 	agents?: AgentChannelLookup,
 	/** The person the running turn is for; their schedules run at their tier. */
 	speaker: () => Speaker | undefined = () => undefined,
 ): ExtensionFactory {
-	const { store, owner, channelFor, prechecks, holds } = schedules;
+	const {
+		store,
+		channelFor,
+		prechecks,
+		holds,
+		visibility,
+		principalOf,
+		target: kept = PERSONAL_TARGET,
+	} = schedules;
 	const defs = scheduleToolSpecs({
 		locale: activeLocale(),
 		timeZone: timeZone(),
@@ -75,27 +92,39 @@ export function schedulesExtension(
 		return {
 			...spec,
 			run: async (input: ToolInput) => {
+				const author = speaker();
+				if (!author)
+					throw new ScheduleError(
+						"schedules are kept only in a turn someone is named for, whose schedules they are",
+					);
 				const peer =
 					agents && typeof input.agent === "string" && input.agent
 						? agents(input.agent)
 						: undefined;
-				const target = peer ?? (await channelFor(channel));
+				const target = peer ?? (await channelFor(channel, author.principalId));
 				const answer = await callScheduleTool(
 					{
 						store,
 						channel: target,
-						target: OWNER_TARGET,
-						author: speaker() ?? owner,
+						target: kept,
+						author: {
+							principalId: author.principalId,
+							id: author.id,
+							name: author.name,
+							tier: author.tier,
+						},
 						now: new Date(),
 						...(prechecks ? { prechecks } : {}),
 						...(holds ? { holds } : {}),
+						...(visibility ? { visibility: await visibility() } : {}),
+						...(principalOf ? { principalOf } : {}),
 					},
 					spec.name,
 					input,
 				);
 				if (peer) return `Agent ${String(input.agent)}'s channel:\n${answer}`;
 				if (target === channel) return answer;
-				return `${answer}\n(These are the schedules of ${identity.name}'s Discord direct messages; their runs are posted there.)`;
+				return `${answer}\n(These are the schedules of ${author.name}'s direct messages; their runs are posted there.)`;
 			},
 		};
 	});

package/src/core/plugin.ts

@@ -17,6 +17,10 @@ import type { HoldCheck, HoldRule } from "./holds.ts";
 import type { HttpRoute } from "./http/listeners.ts";
 import type { Locale } from "./i18n/index.ts";
 import type { Logger } from "./log.ts";
+import type {
+	DirectChannelProvider,
+	DirectChannels,
+} from "./presence/direct-channels.ts";
 import type { ConversationTurns } from "./routing/conversation-turns.ts";
 import type {
 	AgentTurnScope,
@@ -141,6 +145,12 @@ export interface Persona {
 	 * is in the host's language.
 	 */
 	prompt(): string;
+	/**
+	 * Whose memory its conversations read: `"speaker"` (the default), the conversation's person in a
+	 * private one and each turn's speaker in a shared one, or `"none"`: no memory tools and no
+	 * memory in the prompt.
+	 */
+	memory?: "speaker" | "none";
 }
 
 /** What a plugin adds to the process; a plugin that adds nothing is refused. */
@@ -179,6 +189,13 @@ export interface Contribution {
 	 * schedule or delegated task names one, and a turn for a target nobody contributes is skipped.
 	 */
 	backgroundTargets?: readonly BackgroundTarget[];
+	/**
+	 * Ways to reach a person on their own, such as a chat network's direct messages, one per name
+	 * across every plugin. The host reaches a person through the first, in contribution order,
+	 * that reaches them: `notify` sends there, and a conversation no chat surface carries keeps its
+	 * schedules and delegated reports in the creator's.
+	 */
+	directChannels?: readonly DirectChannelProvider[];
 	/** Lines the agent server's dashboard shows under its title, such as links, in contribution order. */
 	dashboard?: readonly string[];
 	/** Tools the plugin adds, each with the lowest tier that may use it; built with `defineTool`. */
@@ -213,6 +230,7 @@ export const CONTRIBUTION_KEYS = [
 	"surfaces",
 	"personas",
 	"backgroundTargets",
+	"directChannels",
 	"dashboard",
 	"tools",
 	"toolTiers",
@@ -235,6 +253,8 @@ export interface LinkedSessions {
 	prompt: readonly PromptSection[];
 	/** The prompt of a conversation kind, from the plugin that contributes its persona; undefined when none does. */
 	persona(kind: string): string | undefined;
+	/** Whose memory conversations of the kind read, as its persona declares; "speaker" when it declares none. */
+	personaMemory?(kind: string): "speaker" | "none";
 	/** Every tool name plugins require at startup, each once. */
 	requiredTools: readonly string[];
 	/** The tools plugins defined for agents, by name. */
@@ -269,6 +289,8 @@ export interface PluginContext {
 	conversations: ConversationPort;
 	/** Every contributed chat surface, chosen by a channel's prefix; calls during setup throw NotLinkedError. */
 	surfaces: SurfacePort;
+	/** Every plugin's direct channels, which reach a person on their own; calls during setup throw NotLinkedError. */
+	directChannels: DirectChannels;
 	/** Runs conversation turns of any kind over the runtime and the surfaces; calls during setup throw NotLinkedError. */
 	turns: ConversationTurns;
 	/** The host's one connection pool, migrated before any setup; throws PluginError without a database. */
@@ -290,10 +312,36 @@ export interface PluginContext {
 	apiKey(provider: string): Promise<string | undefined>;
 }
 
+/**
+ * An identity a plugin's own credential stands for, such as the bearer token of an endpoint it
+ * serves, and the principal it speaks as.
+ */
+export interface PluginIdentity {
+	/**
+	 * Written `token:<subject>`, such as `token:remote-mcp`. Only the `token` provider is accepted:
+	 * a surface's identity, such as `discord:` or `oidc:`, is a person's own account, linked by
+	 * `access.owners` or the CLI, and any other provider stops the boot with a ConfigError.
+	 */
+	identity: string;
+	/** The id of the principal it stands for; the primary owner, the first of `access.owners`, when absent. */
+	principal?: string;
+}
+
 export interface RoundtablePlugin {
 	name: string;
 	/** The plugin's tables; the host runs every plugin's, in registration order, before any setup. */
 	migrations?: readonly Migration[];
+	/**
+	 * Identities the plugin's own credentials stand for, read before any setup. At every boot the
+	 * identity plugin links each to its principal as the plugin's (`roundtable principal list` shows
+	 * them as `plugin`), moves one bound to another principal than at the last boot, and unlinks one
+	 * no plugin declares any more. An identity of a provider other than `token`, one linked to
+	 * someone else, another plugin's, a principal that does not exist, or the system principal stops
+	 * the boot with a ConfigError. A declared
+	 * identity is never admitted or claimed at a first contact, and `IDENTITY.principalOf` reads
+	 * whom it stands for.
+	 */
+	identities?: readonly PluginIdentity[];
 	/** The provider slots the plugin fills, resolved before any setup; two plugins cannot fill one slot. */
 	providers?: Partial<Providers>;
 	/**

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

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