pi-roundtable 0.8.0 → 0.9.0

package/src/core/identity.ts

@@ -1,3 +1,5 @@
+import type { Pronouns } from "./config/config.ts";
+
 /** Who the agents work for, as prompts and tool descriptions name them. */
 export interface OwnerIdentity {
 	name: string;
@@ -7,11 +9,35 @@ export interface OwnerIdentity {
 
 const capital = (word: string) => word.charAt(0).toUpperCase() + word.slice(1);
 
-/** The owner's name and pronouns as prompt text uses them, capitalized for a sentence's start. */
-export function ownerWords(owner: OwnerIdentity): OwnerWords {
-	const { subject, object, possessive } = owner.pronouns;
+/** Each pronoun choice in the words prompts use. */
+export const PRONOUNS: Readonly<Record<Pronouns, OwnerIdentity["pronouns"]>> = {
+	he: { subject: "he", object: "him", possessive: "his" },
+	she: { subject: "she", object: "her", possessive: "her" },
+	they: { subject: "they", object: "them", possessive: "their" },
+};
+
+/**
+ * How prompts name a person: by their pronouns when they gave them, and otherwise by their name,
+ * since a name needs no guess at pronouns.
+ */
+export function addresseeOf(person: {
+	displayName: string;
+	pronouns?: Pronouns;
+}): OwnerIdentity {
+	const name = person.displayName;
 	return {
-		name: owner.name,
+		name,
+		pronouns: person.pronouns
+			? PRONOUNS[person.pronouns]
+			: { subject: name, object: name, possessive: `${name}'s` },
+	};
+}
+
+/** The name and pronouns of whom prompt text addresses, capitalized for a sentence's start. */
+export function addresseeWords(addressee: OwnerIdentity): OwnerWords {
+	const { subject, object, possessive } = addressee.pronouns;
+	return {
+		name: addressee.name,
 		he: subject,
 		He: capital(subject),
 		him: object,
@@ -20,7 +46,10 @@ export function ownerWords(owner: OwnerIdentity): OwnerWords {
 	};
 }
 
-/** The owner's words as `ownerWords` gives them. */
+/** `addresseeWords`, by its name from when every prompt addressed the owner. */
+export const ownerWords = addresseeWords;
+
+/** The words of whom prompt text addresses, as `addresseeWords` gives them. */
 export interface OwnerWords {
 	name: string;
 	he: string;

package/src/core/interactions/prompts.ts

@@ -0,0 +1,127 @@
+import type { ConversationVisibility } from "../conversations/conversation-registry.ts";
+import type { TurnRequest } from "../domain/ports.ts";
+import type { Speaker, Tier } from "../speakers.ts";
+
+/**
+ * How a prompt ended: answered yes or no, unanswered until it expired, or cancelled when its turn
+ * stopped.
+ */
+export type Approval = "approved" | "declined" | "expired" | "cancelled";
+
+export interface AskOption {
+	label: string;
+	description?: string;
+}
+
+export interface OwnerQuestion {
+	question: string;
+	/** Up to 25; none means a free-text answer. */
+	options: readonly AskOption[];
+	/** More than one option may be chosen. */
+	multi: boolean;
+	/** They may write an answer of their own besides the options. */
+	allowOther: boolean;
+}
+
+export interface OwnerAnswer {
+	/** The chosen options' labels, in the order they were offered. */
+	choices: string[];
+	/** What they wrote themselves, if anything. */
+	text?: string;
+}
+
+/**
+ * Who may answer a running turn's prompts: the person whose turn asks, and, in a conversation
+ * others share, the owners. The runtime makes it from the turn's speaker and the conversation's
+ * visibility with `promptScope`.
+ */
+export interface PromptScope {
+	/**
+	 * The principal whose turn asks. They are the person who answers on any of their identities:
+	 * a surface accepts an answer from each identity it knows of theirs, and, where it has none of
+	 * theirs, the prompt is one their tier would not reach.
+	 */
+	principalId: string;
+	/**
+	 * The identity that spoke, as `Speaker.id`: whom a surface addresses the prompt to when it is
+	 * one of its own, or else every identity it knows of the principal. A background turn's may be
+	 * no surface's at all.
+	 */
+	speakerId: string;
+	/**
+	 * Their tier when the turn asked; an approval above it is not theirs, and the surface checks it
+	 * again when they answer where it can. An owner-tier approval is theirs only when the principal
+	 * is an owner: a turn's tier may default to owner without its person being one.
+	 */
+	tier: Tier;
+	/**
+	 * Who else may answer: `owners` in a shared conversation, where an approval above the
+	 * speaker's tier goes to the owners; `none` in a private one, which no one else sees, so such
+	 * an approval expires at once.
+	 */
+	escalate: "owners" | "none";
+}
+
+/**
+ * Prompts inside a running turn, on its conversation's surface: an approval of a held action and an
+ * `ask_user` question, answered by those its `PromptScope` names. Unanswered prompts expire; a
+ * stopped turn cancels its open ones.
+ */
+export interface Prompts {
+	/**
+	 * Asks to approve an action; `signal` cancels the prompt when the turn stops. `minTier` is the
+	 * tier the scope's speaker needs to approve it themselves, `owner` when absent; below it the
+	 * prompt goes to the owners, or, when the scope escalates to no one, resolves `expired` at once.
+	 */
+	confirm(
+		title: string,
+		message: string,
+		signal?: AbortSignal,
+		minTier?: Tier,
+	): Promise<Approval>;
+	/** Asks a question; undefined when it expired or was cancelled. */
+	ask(
+		title: string,
+		question: OwnerQuestion,
+		signal?: AbortSignal,
+	): Promise<OwnerAnswer | undefined>;
+}
+
+/** @deprecated Since 0.9 the prompts are `Prompts`, answered by those their `PromptScope` names; this name goes away in 1.0. */
+export type OwnerPrompts = Prompts;
+
+/**
+ * The scope of a turn's prompts: the speaker's own, escalating to the owners unless the
+ * conversation is private to one principal.
+ */
+export function promptScope(
+	speaker: Speaker,
+	visibility: ConversationVisibility = "shared",
+): PromptScope {
+	return {
+		principalId: speaker.principalId,
+		speakerId: speaker.id,
+		tier: speaker.tier,
+		escalate: visibility === "private" ? "none" : "owners",
+	};
+}
+
+/**
+ * The scope of a turn's prompts, from its speaker and its conversation, shared when the request
+ * names none; undefined for a turn without a speaker, whose prompts are the owners'.
+ */
+export function promptScopeOf(
+	request: Pick<TurnRequest, "speaker" | "conversation">,
+): PromptScope | undefined {
+	return (
+		request.speaker &&
+		promptScope(request.speaker, request.conversation?.visibility)
+	);
+}
+
+/** Whether a `prompts` argument is a scope, not the 0.8 speaker that the port still takes. */
+export function isPromptScope(
+	value: PromptScope | Speaker,
+): value is PromptScope {
+	return "escalate" in value;
+}

package/src/core/modules/background/background-turns.ts

@@ -1,10 +1,12 @@
-import { OWNER_TARGET } from "../../agents/agent-claim.ts";
 import type {
+	BackgroundRunsAs,
+	BackgroundTurn,
 	ConversationPort,
 	ScheduledOutcome,
 } from "../../contract/channels.ts";
 import type { ChannelKey } from "../../domain/conversation.ts";
 import type { Logger } from "../../log.ts";
+import { systemTurn } from "../../routing/system-turns.ts";
 import type { BackgroundTurns } from "../../services.ts";
 import { zonedStamp } from "../../time.ts";
 import {
@@ -15,11 +17,17 @@ import {
 import type { PrecheckFinding } from "../schedules/prechecks.ts";
 import type { Schedule } from "../schedules/schedule-store.ts";
 import { scheduledTurnText } from "../schedules/schedule-tools.ts";
+import { PERSONAL_TARGET } from "./personal-target.ts";
 
 export interface BackgroundTurnsOptions {
-	conversations: Pick<ConversationPort, "background">;
+	conversations: Pick<ConversationPort, "background" | "runsAs">;
 	/** Who a turn the process itself starts, such as a logged error's report, is written by. */
 	system: { id: string; name: string };
+	/**
+	 * 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 taken as the principal's.
+	 */
+	principalOf?: (id: string) => Promise<string | undefined>;
 	logger: Logger;
 }
 
@@ -35,19 +43,40 @@ export class ConversationBackgroundTurns implements BackgroundTurns {
 	}
 
 	/** A due schedule's turn, run as its creator's; with what its precheck found, when it has one. */
-	runScheduled(
+	async runScheduled(
 		schedule: Schedule,
 		firedAt: Date,
 		finding?: PrecheckFinding,
 	): Promise<ScheduledOutcome> {
-		return this.#options.conversations.background({
+		return this.#options.conversations.background(
+			await this.#scheduled(schedule, firedAt, finding),
+		);
+	}
+
+	/** Who a due schedule's turn would run as now, checked as the turn is. */
+	async runsAs(schedule: Schedule): Promise<BackgroundRunsAs> {
+		return this.#options.conversations.runsAs(
+			await this.#scheduled(schedule, new Date()),
+		);
+	}
+
+	/** A due schedule's turn, by its creator: the principal their id stands for, at the schedule's tier. */
+	async #scheduled(
+		schedule: Schedule,
+		firedAt: Date,
+		finding?: PrecheckFinding,
+	): Promise<BackgroundTurn> {
+		const { createdById } = schedule;
+		const principalId =
+			(await this.#options.principalOf?.(createdById)) ?? createdById;
+		return {
 			channel: schedule.channel,
 			target: schedule.target,
-			author: { id: schedule.createdById, name: schedule.createdByName },
+			author: { principalId, id: createdById, name: schedule.createdByName },
 			tier: schedule.createdTier,
 			turnId: `schedule-${schedule.id}-${firedAt.getTime()}`,
 			text: scheduledTurnText(schedule, firedAt, finding),
-		});
+		};
 	}
 
 	/** A delegated task's report, answered in its channel under the same rules as a schedule. */
@@ -58,8 +87,12 @@ export class ConversationBackgroundTurns implements BackgroundTurns {
 		const outcome = await this.#options.conversations.background({
 			channel: job.channel,
 			target: job.target,
-			author: job.author,
-			...(job.author.tier ? { tier: job.author.tier } : {}),
+			author: {
+				principalId: job.author.principalId,
+				id: job.author.id,
+				name: job.author.name,
+			},
+			tier: job.author.tier,
 			turnId: `delegate-${job.id}-${job.startedAt.getTime()}`,
 			text: delegatedTurnText(job, result, zonedStamp(job.startedAt)),
 			report: true,
@@ -71,15 +104,21 @@ export class ConversationBackgroundTurns implements BackgroundTurns {
 			);
 	}
 
-	/** The process's own logged error, reported to an agent in its channel as a report turn. */
+	/**
+	 * The process's own logged error, reported to an agent in its channel as a report turn: the
+	 * host's own, at the owner tier, as in 0.8.
+	 */
 	runErrorReport(channel: ChannelKey, text: string): Promise<ScheduledOutcome> {
-		return this.#options.conversations.background({
-			channel,
-			target: OWNER_TARGET.name,
-			author: this.#options.system,
-			turnId: `error-${Date.now()}`,
-			text,
-			report: true,
-		});
+		return this.#options.conversations.background(
+			systemTurn({
+				channel,
+				target: PERSONAL_TARGET.name,
+				author: this.#options.system,
+				tier: "owner",
+				turnId: `error-${Date.now()}`,
+				text,
+				report: true,
+			}),
+		);
 	}
 }

package/src/core/modules/background/personal-target.ts

@@ -0,0 +1,50 @@
+import type { BackgroundTarget } from "../../contract/channels.ts";
+import { messages } from "../../i18n/index.ts";
+
+/**
+ * The host's own background target: every person's conversations whose claim answers background
+ * turns, such as the owner's and the agent server's on Discord. The modules plugin contributes it
+ * on every host, so schedules and delegated tasks made there carry its name and limits; its name
+ * stays "owner", as 0.8 stored it. Its label is read when a list is shown, never when this module
+ * loads, because the host applies its catalog at startup.
+ */
+export const PERSONAL_TARGET: BackgroundTarget = {
+	name: "owner",
+	label: () => messages().scheduleModeOwner,
+	schedules: { perChannel: 20, promptChars: 8_000, aheadDays: 366 },
+	delegation: { maxRunning: 3 },
+};
+
+/** How many schedules, and running delegated tasks, one person may have across their conversations. */
+export interface PerPrincipalLimits {
+	schedules?: number;
+	delegations?: number;
+}
+
+/**
+ * `PERSONAL_TARGET` holding each person to `limits` across all their conversations: as many
+ * schedules (`perPrincipal`) and running delegated tasks (`maxRunningPerPrincipal`) as given; a
+ * limit left out is unset, as in `PERSONAL_TARGET`.
+ */
+export function personalTarget(
+	limits: PerPrincipalLimits = {},
+): BackgroundTarget {
+	const { schedules, delegation } = PERSONAL_TARGET;
+	if (!schedules || !delegation)
+		throw new Error("the personal target schedules and delegates");
+	return {
+		...PERSONAL_TARGET,
+		schedules: {
+			...schedules,
+			...(limits.schedules === undefined
+				? {}
+				: { perPrincipal: limits.schedules }),
+		},
+		delegation: {
+			...delegation,
+			...(limits.delegations === undefined
+				? {}
+				: { maxRunningPerPrincipal: limits.delegations }),
+		},
+	};
+}

package/src/core/modules/delegation/delegate.ts

@@ -1,28 +1,27 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import { OWNER_TARGET } from "../../agents/agent-claim.ts";
 import type { ChannelKey } from "../../domain/conversation.ts";
 import { DelegationError } from "../../domain/errors.ts";
-import type { OwnerIdentity } from "../../identity.ts";
+import { SYSTEM_PRINCIPAL } from "../../identity/principal-store.ts";
 import { textToolsExtension } from "../../runtime/text-tools.ts";
 import type { Delegator } from "../../services.ts";
 import { DELEGATE_TOOL_SPEC } from "../../shared/delegate-tool.ts";
 import type { Speaker } from "../../speakers.ts";
+import { PERSONAL_TARGET } from "../background/personal-target.ts";
 
 export interface OwnerDelegation {
 	delegator: Pick<Delegator, "start">;
-	owner: { id: string; name: string };
-	/** The chat channel a conversation's reports go to, as for schedules. */
-	channelFor: (channel: ChannelKey) => Promise<ChannelKey>;
+	/** The chat channel a conversation's reports go to, as for schedules, asked with the asker's principal. */
+	channelFor: (channel: ChannelKey, principalId: string) => Promise<ChannelKey>;
 }
 
 /**
- * Registers delegate_task for one owner conversation. `origin` is the channel its turns run
- * in, where each job's thread opens: a group's, for an agent's seat in one.
+ * Registers delegate_task for one conversation; a job reports as the person whose turn started
+ * it, and in a turn nobody is named for, or the host's own, the tool refuses. `origin` is the
+ * channel its turns run in, where each job's thread opens: a group's, for an agent's seat in one.
  */
 export function delegateExtension(
 	delegation: OwnerDelegation,
 	channel: ChannelKey,
-	identity: OwnerIdentity,
 	origin: ChannelKey = channel,
 	/** The person the running turn is for; the report comes back at their tier. */
 	speaker: () => Speaker | undefined = () => undefined,
@@ -32,20 +31,35 @@ export function delegateExtension(
 			{
 				...DELEGATE_TOOL_SPEC,
 				run: async (input) => {
+					const author = speaker();
+					if (!author)
+						throw new DelegationError(
+							"a task is delegated only in a turn someone is named for, whose report it is",
+						);
+					if (author.principalId === SYSTEM_PRINCIPAL)
+						throw new DelegationError(
+							"the host's own turns, such as a report's, delegate no tasks; ask the owner to",
+						);
 					const { title, task } = input as { title: string; task: string };
-					const target = await delegation.channelFor(channel);
+					const target = await delegation.channelFor(
+						channel,
+						author.principalId,
+					);
 					const job = delegation.delegator.start({
 						channel: target,
 						origin,
-						target: OWNER_TARGET.name,
-						author: speaker() ?? delegation.owner,
+						target: PERSONAL_TARGET.name,
+						author: {
+							principalId: author.principalId,
+							id: author.id,
+							name: author.name,
+							tier: author.tier,
+						},
 						title,
 						task,
 					});
 					const where =
-						target === channel
-							? "here"
-							: `in ${identity.name}'s Discord direct messages`;
+						target === channel ? "here" : `in ${author.name}'s direct messages`;
 					return `Delegated as task #${job.id}; the report comes back ${where} as a new turn.`;
 				},
 			},

package/src/core/modules/delegation/delegator.ts

@@ -19,8 +19,11 @@ export interface DelegationJob {
 	origin?: ChannelKey;
 	/** The name of the background target the report is answered as. */
 	target: string;
-	/** Who asked; the report is answered as this person's turn. */
-	author: { id: string; name: string; tier?: Tier };
+	/**
+	 * Who asked: their principal, the id and name they spoke as, and their tier; the report is
+	 * answered as this person's turn, at that tier or theirs then, whichever is lower.
+	 */
+	author: { principalId: string; id: string; name: string; tier: Tier };
 	title: string;
 	task: string;
 	startedAt: Date;
@@ -78,18 +81,31 @@ export class DefaultDelegator implements Delegator {
 			throw new DelegationError(
 				`the task is ${task.length} characters; keep it within ${MAX_TASK_CHARS}`,
 			);
-		const busy = [...this.#running.values()].filter(
-			({ job }) => job.channel === request.channel,
+		const running = [...this.#running.values()].map(({ job }) => job);
+		const busy = running.filter(
+			(job) => job.channel === request.channel,
 		).length;
-		const limit = this.#options.targets(request.target)?.delegation?.maxRunning;
-		if (limit === undefined)
+		const limits = this.#options.targets(request.target)?.delegation;
+		if (limits === undefined)
 			throw new DelegationError(
 				`delegated tasks are not available for ${request.target} conversations`,
 			);
-		if (busy >= limit)
+		if (busy >= limits.maxRunning)
 			throw new DelegationError(
 				`this channel already has ${busy} delegated tasks running; wait for one to report back`,
 			);
+		const perPrincipal = limits.maxRunningPerPrincipal;
+		if (perPrincipal !== undefined) {
+			const theirs = running.filter(
+				(job) =>
+					job.target === request.target &&
+					job.author.principalId === request.author.principalId,
+			).length;
+			if (theirs >= perPrincipal)
+				throw new DelegationError(
+					`you already have ${theirs} delegated tasks running, the most one person may have here; wait for one to report back`,
+				);
+		}
 		const job: DelegationJob = {
 			...request,
 			title,