pi-roundtable 0.7.19 → 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/ops/error-reporter.ts

@@ -19,20 +19,28 @@ const OWN_KEYS = new Set(["level", "time", "pid", "hostname", "msg", "err"]);
 const HEAD_KEYS = ["app", "plugin", "module"];
 const APP_FRAME = /((?:src|shared|worker)\/[^\s():]+\.ts):(\d+)/;
 
-/** Where the reports go, known once the Discord surface and the agent team are up. */
+/** Who investigates the errors: an agent, in its channel, or the claim of one conversation. */
+export type ErrorReportDestination =
+	| { agent: string }
+	| { conversation: ChannelKey };
+
+/** How the reports are delivered, known once the surfaces, and for an agent the team, are up. */
 export interface ErrorReportDelivery {
-	/** The agent's channel while it is active; undefined for an archived or unknown agent. */
-	channelOf(agent: string): ChannelKey | undefined;
-	/** The visible message in the agent's channel. */
+	/**
+	 * The agent's channel while it is active; undefined for an archived or unknown agent. Asked
+	 * only for an agent's reports.
+	 */
+	channelOf?(agent: string): ChannelKey | undefined;
+	/** The visible message in the channel. */
 	post(channel: ChannelKey, text: string): Promise<void>;
-	/** The agent's report turn; resolves when it has run. */
+	/** The report turn; resolves when it has run. */
 	turn(channel: ChannelKey, text: string): Promise<ScheduledOutcome>;
 	logger: Logger;
 }
 
 export interface ErrorReporterOptions {
-	/** The agent that investigates the errors, reported in its channel. */
-	opsAgent: string;
+	/** Who investigates the errors. */
+	destination: ErrorReportDestination;
 	/** The name the reports give the process, such as "Roundtable". */
 	app: string;
 	ignored?: readonly RegExp[];
@@ -43,14 +51,14 @@ export interface ErrorReporterOptions {
 }
 
 /**
- * The process's own `error` and `fatal` log entries, each reported to the ops agent as a visible
- * message and a report turn in its channel. The same error goes at most once an hour, and at
+ * The process's own `error` and `fatal` log entries, each reported to the ops agent or the ops
+ * conversation as a visible message and a report turn in its channel. The same error goes at most once an hour, and at
  * most five reports an hour overall; the rest are counted and summed up in one report when the
  * hour allows. Errors from the reporting itself are only logged; errors logged elsewhere while
  * an error-report turn runs are counted and summed up once it ends.
  */
 export class ErrorReporter {
-	readonly #opsAgent: string;
+	readonly destination: ErrorReportDestination;
 	readonly #app: string;
 	readonly #ignored: readonly RegExp[];
 	readonly #now: () => number;
@@ -68,7 +76,7 @@ export class ErrorReporter {
 	#summaryDue = false;
 
 	constructor(options: ErrorReporterOptions) {
-		this.#opsAgent = options.opsAgent;
+		this.destination = options.destination;
 		this.#app = options.app;
 		this.#ignored = options.ignored ?? IGNORED_ERRORS;
 		this.#now = options.now ?? Date.now;
@@ -177,7 +185,11 @@ export class ErrorReporter {
 		const delivery = this.#delivery;
 		if (!delivery) return Promise.resolve();
 		return this.#reporting.run(true, async () => {
-			const channel = delivery.channelOf(this.#opsAgent);
+			const { destination } = this;
+			const channel =
+				"conversation" in destination
+					? destination.conversation
+					: delivery.channelOf?.(destination.agent);
 			if (!channel) return;
 			try {
 				await delivery.post(channel, text);

package/src/core/plugin.ts

@@ -11,11 +11,16 @@ import type { ServiceKey, Services } from "./contract/services.ts";
 import type { ChatSurface, SurfacePort } from "./contract/surface.ts";
 import type { Migration } from "./db/migrations.ts";
 import type { ToolContribution } from "./define.ts";
+import type { TurnProgress } from "./domain/progress.ts";
 import { PluginError } from "./errors.ts";
 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,
@@ -75,6 +80,11 @@ export interface TurnEndEvent extends TurnEvent {
 	result: "ok" | "failed" | "stopped";
 }
 
+/** What a running turn wrote or ran, as a handler hears of it, between its start and its end. */
+export interface TurnProgressEvent extends TurnEvent {
+	progress: TurnProgress;
+}
+
 /** What a plugin may react to; a handler that throws is logged and never stops the others. */
 export interface EventHandlers {
 	/**
@@ -87,6 +97,12 @@ export interface EventHandlers {
 	turnStarted?(turn: TurnEvent): Promise<void> | void;
 	/** A turn that began ended, however it ended. */
 	turnEnded?(turn: TurnEndEvent): Promise<void> | void;
+	/**
+	 * A turn run through `context.turns` wrote text or ran a tool, as it goes: text joined over a
+	 * short interval, and each tool's name with a short preview of its arguments. Turns on a runtime
+	 * without live progress report none.
+	 */
+	turnProgress?(event: TurnProgressEvent): Promise<void> | void;
 	/** The team changed: an agent or group was created, edited, arranged, archived, or started over. */
 	changed?(): Promise<void> | void;
 	/** The shutdown drain ended, before any service stops; `left` is the work it gave up on. */
@@ -97,6 +113,8 @@ export interface EventHandlers {
 export interface EventSink {
 	turnStarted(turn: TurnEvent): void;
 	turnEnded(turn: TurnEndEvent): void;
+	/** Optional, so a sink of your own written before it still fits. */
+	turnProgress?(event: TurnProgressEvent): void;
 	changed(): void;
 }
 
@@ -127,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. */
@@ -165,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`. */
@@ -199,6 +230,7 @@ export const CONTRIBUTION_KEYS = [
 	"surfaces",
 	"personas",
 	"backgroundTargets",
+	"directChannels",
 	"dashboard",
 	"tools",
 	"toolTiers",
@@ -221,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. */
@@ -255,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. */
@@ -276,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>;
 	/**