pi-roundtable 0.8.0 → 0.9.0

package/src/core/modules/memory/owner-memory.ts

@@ -1,10 +1,9 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { messages } from "../../i18n/index.ts";
-import { type OwnerIdentity, ownerWords } from "../../identity.ts";
+import { addresseeWords, type OwnerIdentity } from "../../identity.ts";
 import type { MemoryStore } from "../../services.ts";
 import { toolError, toolText } from "../../shared/tool-result.ts";
-import type { Speaker } from "../../speakers.ts";
 import { timeZone, zonedToday } from "../../time.ts";
 import type { Memory, PromptMemory } from "./owner-memory-store.ts";
 
@@ -17,8 +16,8 @@ function line(memory: Memory): string {
 export function ownerMemorySection(
 	memory: PromptMemory,
 	today: string,
-	/** Whose memory it is, when not the owner's. */
-	speaker?: Speaker,
+	/** The name of whose memory it is, when not the primary owner's. */
+	name?: string,
 ): string {
 	const core =
 		memory.core.length > 0
@@ -27,7 +26,7 @@ export function ownerMemorySection(
 	const events =
 		memory.events.length > 0 ? memory.events.map(line).join("\n") : "(none)";
 	return [
-		speaker ? `## Memory of ${speaker.name}` : "## Owner memory",
+		name === undefined ? "## Owner memory" : `## Memory of ${name}`,
 		`Today in ${messages().zoneName(timeZone())} is ${today}. What is stored right now, including anything you added earlier in this conversation; each appears once.`,
 		`### Core facts\n${core}`,
 		`### Upcoming events\n${events}`,
@@ -35,42 +34,92 @@ export function ownerMemorySection(
 	].join("\n\n");
 }
 
+/** Whose memory a session's turns read, and how its tools name them. */
+export interface MemoryFor {
+	/** The primary owner's principal, whose memory keeps 0.8's "Owner memory" heading. */
+	ownerId: string;
+	/** Whom the tool descriptions address: a private conversation's person, or `THE_SPEAKER`. */
+	addressee: OwnerIdentity;
+	/** Whether the tools tell the model that each speaker has a memory of their own, as in a shared conversation. */
+	describesSpeakers: boolean;
+	/** Whose memory the running turn reads and changes, and their name; undefined when it is no one's. */
+	whose(): { principalId: string; name: string } | undefined;
+}
+
+/** The memory tools, whose results hold one person's memory. */
+export const MEMORY_TOOLS = [
+	"memory_add",
+	"memory_search",
+	"memory_remove",
+] as const;
+
+/** What a memory tool's result records in the session: whose memory it holds. */
+interface PrivateMemory {
+	privateTo: string;
+}
+
+/** A memory tool's answer from the principal's memory, which records whose it is. */
+function privateText(text: string, principalId: string) {
+	const details: PrivateMemory = { privateTo: principalId };
+	return { ...toolText(text), details };
+}
+
 /**
- * Adds the owner's core facts and upcoming events to every run, and registers
- * memory_add, memory_search, and memory_remove. The section goes into appendSystemPrompt
- * because claude-bridge forwards only the prompt's option sections to Claude Code, not a
- * replaced system prompt.
+ * The call's answer, or, when it fails, such as with the store unreachable, its error recording
+ * whose memory the call was for: its arguments are what the model wrote from that memory.
+ */
+async function ownAnswer<T>(
+	principalId: string,
+	answer: () => Promise<T>,
+): Promise<T | (ReturnType<typeof toolError> & { details: PrivateMemory })> {
+	try {
+		return await answer();
+	} catch (error) {
+		const details: PrivateMemory = { privateTo: principalId };
+		return {
+			...toolError(error instanceof Error ? error.message : String(error)),
+			details,
+		};
+	}
+}
+
+/** What the memory tools answer in a turn that reads no one's memory, such as the host's own report. */
+const NO_ONE =
+	"This turn reads no one's memory, so there is nothing to remember, search, or forget in it.";
+
+/**
+ * Adds the core facts and upcoming events of whose memory the turn reads to every run, and
+ * registers memory_add, memory_search, and memory_remove over it. The section goes into
+ * appendSystemPrompt because claude-bridge forwards only the prompt's option sections to Claude
+ * Code, not a replaced system prompt.
  */
 export function ownerMemoryExtension(
 	memories: MemoryStore,
-	/** The owner's Discord id: the speaker whose memory a turn reads when no other speaks. */
-	ownerId: string,
-	owner: OwnerIdentity,
-	/**
-	 * The person the running turn is for, when it may be someone other than the owner. Their
-	 * memory, not the owner's, is what the turn reads and changes; without it every turn is the owner's.
-	 */
-	speaker?: () => Speaker | undefined,
-	/** Whether the tools tell the model that each speaker has a memory of their own. */
-	describesSpeakers = speaker !== undefined,
+	memory: MemoryFor,
 ): ExtensionFactory {
-	const o = ownerWords(owner);
-	/** The running turn's other speaker; undefined when the owner's own memory applies. */
-	const other = (): Speaker | undefined => {
-		const current = speaker?.();
-		return current && current.id !== ownerId ? current : undefined;
+	const o = addresseeWords(memory.addressee);
+	// Whose memory the call reads and changes; its result records them.
+	const storeOf = () => {
+		const whose = memory.whose();
+		return (
+			whose && {
+				store: memories.forSpeaker(whose.principalId),
+				whose: whose.principalId,
+			}
+		);
 	};
-	const storeOf = () => memories.forSpeaker(other()?.id ?? ownerId);
-	const shared = describesSpeakers
+	const shared = memory.describesSpeakers
 		? " Whoever is speaking has a memory of their own, shared by every agent; this reads and changes theirs, not someone else's."
 		: "";
 	return (pi) => {
 		pi.on("before_agent_start", async (event) => {
+			const whose = memory.whose();
+			if (!whose) return;
 			const today = zonedToday();
 			const section = ownerMemorySection(
-				await storeOf().forPrompt(today),
+				await memories.forSpeaker(whose.principalId).forPrompt(today),
 				today,
-				other(),
+				whose.principalId === memory.ownerId ? undefined : whose.name,
 			);
 			const appended = event.systemPromptOptions.appendSystemPrompt;
 			event.systemPromptOptions.appendSystemPrompt = appended
@@ -98,12 +147,19 @@ export function ownerMemoryExtension(
 				),
 			}),
 			execute: async (_toolCallId, params) => {
-				const saved = await storeOf().add(
-					params.fact,
-					params.kind,
-					params.date,
-				);
-				return toolText(`Remembered as ${saved.kind}: ${line(saved).slice(2)}`);
+				const of = storeOf();
+				if (!of) return toolError(NO_ONE);
+				return ownAnswer(of.whose, async () => {
+					const saved = await of.store.add(
+						params.fact,
+						params.kind,
+						params.date,
+					);
+					return privateText(
+						`Remembered as ${saved.kind}: ${line(saved).slice(2)}`,
+						of.whose,
+					);
+				});
 			},
 		});
 
@@ -115,14 +171,21 @@ export function ownerMemoryExtension(
 				query: Type.String({ description: "Keywords separated by spaces." }),
 			}),
 			execute: async (_toolCallId, params) => {
-				const found = await storeOf().search(params.query);
-				return toolText(
-					found.length === 0
-						? `Nothing remembered matches "${params.query}".`
-						: found
-								.map((memory) => `- [${memory.kind}] ${line(memory).slice(2)}`)
-								.join("\n"),
-				);
+				const of = storeOf();
+				if (!of) return toolError(NO_ONE);
+				return ownAnswer(of.whose, async () => {
+					const found = await of.store.search(params.query);
+					return privateText(
+						found.length === 0
+							? `Nothing remembered matches "${params.query}".`
+							: found
+									.map(
+										(memory) => `- [${memory.kind}] ${line(memory).slice(2)}`,
+									)
+									.join("\n"),
+						of.whose,
+					);
+				});
 			},
 		});
 
@@ -136,15 +199,25 @@ export function ownerMemoryExtension(
 				}),
 			}),
 			execute: async (_toolCallId, params) => {
-				const removed = await storeOf().remove(params.text);
-				if (removed.length === 0) {
-					return toolError(
-						`No remembered fact contains "${params.text}". Nothing was forgotten.`,
+				const of = storeOf();
+				if (!of) return toolError(NO_ONE);
+				return ownAnswer(of.whose, async () => {
+					const removed = await of.store.remove(params.text);
+					// The refusal repeats the text, which may be the person's memory, so it records whose too.
+					if (removed.length === 0) {
+						const details: PrivateMemory = { privateTo: of.whose };
+						return {
+							...toolError(
+								`No remembered fact contains "${params.text}". Nothing was forgotten.`,
+							),
+							details,
+						};
+					}
+					return privateText(
+						`Forgot:\n${removed.map((fact) => `- ${fact}`).join("\n")}`,
+						of.whose,
 					);
-				}
-				return toolText(
-					`Forgot:\n${removed.map((fact) => `- ${fact}`).join("\n")}`,
-				);
+				});
 			},
 		});
 	};

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

@@ -1,26 +1,66 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { OwnerNotifier } from "../../domain/ports.ts";
-import { type OwnerIdentity, ownerWords } from "../../identity.ts";
-import { toolText } from "../../shared/tool-result.ts";
+import type { Notifier } from "../../domain/ports.ts";
+import { addresseeWords, type OwnerIdentity } from "../../identity.ts";
+import { toolError, toolText } from "../../shared/tool-result.ts";
 
+/** What notify needs in one session. */
+export interface SessionNotify {
+	/** Sends a person a notice through their own channel; false when none reaches them. */
+	notifier: Notifier;
+	/**
+	 * Whom a call notifies, read when it runs: the conversation's person in a private one, the
+	 * turn's speaker in a shared one; or why nobody is, such as in a turn nobody is named for.
+	 */
+	recipient: () => Promise<{ principalId: string } | { refused: string }>;
+	/** How a notice reaches them, completing "Send Ada …", such as "a direct message on Discord". */
+	channels: string;
+}
+
+/**
+ * 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,
+ * `notify_owner`, still names it in a selection and in `toolTiers` until 1.0 (`RENAMED_TOOLS`).
+ */
 export function notifyExtension(
-	notifier: OwnerNotifier,
-	owner: OwnerIdentity,
+	notify: SessionNotify,
+	/** Whom the description names: the private conversation's person, or the speaker. */
+	addressee: OwnerIdentity,
+	/**
+	 * Whom it names at each turn, when that may change while the session is open, such as when the
+	 * host gains or loses an owner; the tool is described anew before a turn whose words differ.
+	 */
+	current?: () => Promise<OwnerIdentity>,
 ): ExtensionFactory {
-	const o = ownerWords(owner);
-	return (pi) => {
-		pi.registerTool({
-			name: "notify_owner",
-			label: "Notify owner",
-			description: `Send ${o.name} a direct message on Discord. Use only when ${o.he} asks to be notified or reminded by DM; your normal reply already reaches ${o.him}.`,
+	const tool = (who: OwnerIdentity) => {
+		const o = addresseeWords(who);
+		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}.`,
 			parameters: Type.Object({
 				text: Type.String({ description: "The message to send." }),
 			}),
-			execute: async (_toolCallId, params) => {
-				await notifier.notifyOwner(params.text);
+			execute: async (_toolCallId: string, params: { text: string }) => {
+				const recipient = await notify.recipient();
+				if ("refused" in recipient) return toolError(recipient.refused);
+				if (!(await notify.notifier.notify(recipient.principalId, params.text)))
+					return toolError(
+						"the person this notice is for has no direct channel on this host to send it to",
+					);
 				return toolText("Sent.");
 			},
+		};
+	};
+	return (pi) => {
+		let described = tool(addressee);
+		pi.registerTool(described);
+		if (!current) return;
+		pi.on("before_agent_start", async () => {
+			const now = tool(await current());
+			if (now.description === described.description) return;
+			described = now;
+			pi.registerTool(now);
 		});
 	};
 }

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

@@ -0,0 +1,110 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { SYSTEM_PRINCIPAL } from "../../identity/principal-store.ts";
+import type { OwnerIdentity } from "../../identity.ts";
+import type { Logger } from "../../log.ts";
+import type {
+	DirectChannelProvider,
+	DirectChannels,
+} from "../../presence/direct-channels.ts";
+import type { SessionContext } from "../../sessions.ts";
+import { notifyExtension } from "./notify.ts";
+
+export interface SessionNotifyDeps {
+	directChannels: DirectChannels;
+	/** The primary owner: the host's own turns, such as a report's, notify them, as 0.8 did. */
+	owner: OwnerIdentity & { id: string };
+	/**
+	 * Whether a notice in a shared conversation can only be the primary owner's: the host has no
+	 * other owner, and only owners may use notify. Its description then names them, as in 0.8.
+	 */
+	onlyOwnerNotified(): Promise<boolean>;
+	logger: Logger;
+}
+
+/** "a direct message on Discord", or each provider's label joined with "or". */
+function labels(providers: readonly DirectChannelProvider[]): string {
+	return providers.map((provider) => provider.label).join(" or ");
+}
+
+/**
+ * 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.
+ */
+export function sessionNotify(
+	deps: SessionNotifyDeps,
+): (session: SessionContext) => ExtensionFactory | null {
+	const { directChannels, owner, logger } = deps;
+	// Whom a notice is for: the person of a private conversation, the speaker of a shared one; the
+	// host's own turns notify the conversation's person, or else the primary owner. Anyone else
+	// speaking in someone's private conversation is refused, so their text never reaches its person.
+	const recipientOf = (
+		session: SessionContext,
+		own: string | undefined,
+	): { principalId: string } | { refused: string } => {
+		const speaker = session.speaker();
+		if (!speaker)
+			return {
+				refused:
+					"a notice is sent only in a turn someone is named for, whose notice it is",
+			};
+		if (speaker.principalId === SYSTEM_PRINCIPAL)
+			return { principalId: own ?? owner.id };
+		if (own !== undefined && speaker.principalId !== own)
+			return {
+				refused:
+					"this conversation is private to someone else, so a notice here is not yours to send",
+			};
+		return { principalId: speaker.principalId };
+	};
+	// A failed lookup names no one: the speaker's words are true whoever it is.
+	const onlyOwner = (session: SessionContext) =>
+		deps.onlyOwnerNotified().catch((error: unknown) => {
+			logger.warn(
+				{ channel: session.homeChannel, err: error },
+				"could not tell whether the primary owner is the only owner",
+			);
+			return false;
+		});
+	return (session) => {
+		const providers = directChannels.providers();
+		if (providers.length === 0) return null;
+		const { conversation } = session;
+		const own =
+			conversation.visibility === "private"
+				? conversation.principalId
+				: undefined;
+		return async (pi) => {
+			let reaching = providers;
+			if (own !== undefined) {
+				try {
+					const known = await directChannels.known(own);
+					if (!known) return;
+					reaching = [known];
+				} catch (error) {
+					// No destination was established; do not advertise an unusable tool.
+					logger.warn(
+						{ channel: session.homeChannel, err: error },
+						"could not tell whether a direct channel reaches the conversation's person",
+					);
+					return;
+				}
+			}
+			// A shared conversation names the primary owner while only they can be notified, which
+			// an owner granted or revoked while the session is open changes before its next turn.
+			const describe = async () =>
+				own === undefined && (await onlyOwner(session))
+					? owner
+					: session.addressee;
+			await notifyExtension(
+				{
+					notifier: directChannels,
+					recipient: async () => recipientOf(session, own),
+					channels: labels(reaching),
+				},
+				await describe(),
+				own === undefined ? describe : undefined,
+			)(pi);
+		};
+	};
+}

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

@@ -35,6 +35,11 @@ export interface PrecheckContext {
 	/** The due schedule, already moved to its next run (or deleted, when it runs once). */
 	schedule: Schedule;
 	firedAt: Date;
+	/**
+	 * The tier this run is for: the schedule's, capped at what its creator holds now, as its turn
+	 * would run. A precheck runs only for a creator who may run the turn.
+	 */
+	tier: Tier;
 	/** Aborted when the precheck runs out of time or the host stops; its answer is then ignored. */
 	signal: AbortSignal;
 }
@@ -61,8 +66,9 @@ export interface PrecheckScope {
 	/** The schedule's background target, such as the owner's. */
 	target: string;
 	/**
-	 * The tier of whoever set the script: its creator's when it runs, the asker's when schedule_list
-	 * describes it; absent when the asker's is unknown. A runner may grant lower tiers less.
+	 * The tier of whoever set the script: the run's (`PrecheckContext.tier`) when it runs, the
+	 * asker's when schedule_list describes it; absent when the asker's is unknown. A runner may grant
+	 * lower tiers less.
 	 */
 	tier?: Tier;
 }

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

@@ -1,5 +1,6 @@
 import type { HoldCheck } from "../../holds.ts";
 import type { Logger } from "../../log.ts";
+import type { Tier } from "../../speakers.ts";
 import { timeZone, zonedStamp } from "../../time.ts";
 import { type PrecheckTool, precheckScriptTools } from "./precheck-tools.ts";
 import {
@@ -33,10 +34,12 @@ export class SchedulePrechecks {
 		this.#options = options;
 	}
 
+	/** Runs the schedule's precheck for a run at `tier`, its creator's capped tier now. */
 	async run(
 		schedule: Schedule,
 		name: string,
 		firedAt: Date,
+		tier: Tier,
 	): Promise<PrecheckOutcome> {
 		const { logger } = this.#options;
 		let decision: PrecheckOutcome;
@@ -47,7 +50,7 @@ export class SchedulePrechecks {
 					? { kind: "failed", error: precheck }
 					: await runPrecheck(
 							precheck,
-							{ schedule, firedAt },
+							{ schedule, firedAt, tier },
 							{
 								signal: this.#options.signal,
 								settled: (run) => {

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

@@ -110,6 +110,34 @@ function toSchedule(row: Row): Schedule {
 	};
 }
 
+/** Refuses a schedule the table could not run: a precheck and a script both, or a script without its tools. */
+function checked(schedule: NewSchedule): void {
+	if (schedule.precheck && schedule.precheckScript)
+		throw new ScheduleError(
+			"a schedule has a precheck or a precheck script, not both",
+		);
+	if (schedule.precheckScript && !schedule.precheckTools)
+		throw new ScheduleError(
+			"a precheck script is saved with the tools it may call",
+		);
+}
+
+async function insert(sql: SQL, schedule: NewSchedule): Promise<Schedule> {
+	checked(schedule);
+	const rows: Row[] = await sql`
+		INSERT INTO schedules (channel_key, mode, title, prompt, recurrence, next_run,
+			created_by_id, created_by_name, created_tier, precheck, precheck_script, precheck_tools)
+		VALUES (${schedule.channel}, ${schedule.target}, ${schedule.title}, ${schedule.prompt},
+			${JSON.stringify(schedule.recurrence)}, ${schedule.nextRun},
+			${schedule.createdById}, ${schedule.createdByName}, ${schedule.createdTier},
+			${schedule.precheck ?? null}, ${schedule.precheckScript ?? null},
+			${schedule.precheckScript ? JSON.stringify(schedule.precheckTools) : null})
+		RETURNING *`;
+	const [row] = rows;
+	if (!row) throw new Error("the schedule insert returned no row");
+	return toSchedule(row);
+}
+
 /** Scheduled turns, in the database. A one-time schedule's row is deleted once it fires. */
 export class PgScheduleStore implements ScheduleStore {
 	readonly #sql: SQL;
@@ -176,26 +204,29 @@ export class PgScheduleStore implements ScheduleStore {
 	}
 
 	async create(schedule: NewSchedule): Promise<Schedule> {
-		if (schedule.precheck && schedule.precheckScript)
-			throw new ScheduleError(
-				"a schedule has a precheck or a precheck script, not both",
-			);
-		if (schedule.precheckScript && !schedule.precheckTools)
-			throw new ScheduleError(
-				"a precheck script is saved with the tools it may call",
-			);
-		const rows: Row[] = await this.#sql`
-			INSERT INTO schedules (channel_key, mode, title, prompt, recurrence, next_run,
-				created_by_id, created_by_name, created_tier, precheck, precheck_script, precheck_tools)
-			VALUES (${schedule.channel}, ${schedule.target}, ${schedule.title}, ${schedule.prompt},
-				${JSON.stringify(schedule.recurrence)}, ${schedule.nextRun},
-				${schedule.createdById}, ${schedule.createdByName}, ${schedule.createdTier},
-				${schedule.precheck ?? null}, ${schedule.precheckScript ?? null},
-				${schedule.precheckScript ? JSON.stringify(schedule.precheckTools) : null})
-			RETURNING *`;
-		const [row] = rows;
-		if (!row) throw new Error("the schedule insert returned no row");
-		return toSchedule(row);
+		return insert(this.#sql, schedule);
+	}
+
+	/**
+	 * Creates a schedule unless its creator already has `limit.max` of its target's schedules,
+	 * counting those whose creator id is one of `limit.creators`; resolves the count reached instead.
+	 * The count and the insert hold a lock on the creator, so creates at once by one person in many
+	 * conversations stay within the limit.
+	 */
+	async createWithin(
+		schedule: NewSchedule,
+		limit: { creators: readonly string[]; max: number },
+	): Promise<{ created: Schedule } | { reached: number }> {
+		checked(schedule);
+		return this.#sql.begin(async (tx) => {
+			await tx`SELECT pg_advisory_xact_lock(hashtextextended(${`schedules/creator:${schedule.createdById}`}, 0))`;
+			const [row]: { count: string | number }[] = await tx`
+				SELECT count(*) AS count FROM schedules
+				WHERE mode = ${schedule.target} AND created_by_id IN ${tx([...limit.creators])}`;
+			const count = Number(row?.count ?? 0);
+			if (count >= limit.max) return { reached: count };
+			return { created: await insert(tx, schedule) };
+		});
 	}
 
 	async get(id: number): Promise<Schedule | undefined> {