pi-roundtable 0.26.0 → 0.26.2

package/src/core/agents/agent-messages.ts

@@ -1,9 +1,13 @@
 import type { ChannelKey } from "../domain/conversation.ts";
-import { AgentError } from "../domain/errors.ts";
+import { AgentError, IdentityError } from "../domain/errors.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
+import { HostStoppingError } from "../errors.ts";
 import { messages } from "../i18n/index.ts";
+import { SYSTEM_PRINCIPAL } from "../identity/principal-store.ts";
+import { isQuiet } from "../presentation/reply-body.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
-import { addressee } from "../speakers.ts";
+import { addressee, type Speaker } from "../speakers.ts";
+import type { OutboxEntry, StoredOutboxEntry } from "./agent-outbox.ts";
 import {
 	agentFailureText,
 	agentMessageText,
@@ -13,13 +17,8 @@ import {
 	returnedAnswerPost,
 } from "./agent-prompt.ts";
 import type { Agent } from "./agent-store.ts";
-import {
-	agentRoomKey,
-	discordKey,
-	homeScope,
-	roomScope,
-	roomSurfaceOf,
-} from "./team-keys.ts";
+import { conversationLabel, messageTarget } from "./message-target.ts";
+import { discordIdOf, discordKey, scopeOf } from "./team-keys.ts";
 import {
 	type Chain,
 	type Exchange,
@@ -30,22 +29,43 @@ import {
 /** Messages between agents: each runs the target's turn, then wakes the sender with the answer. */
 export class AgentMessages {
 	readonly #host: TurnHost;
+	/** The writes of entries the host refused while it stopped, which the shutdown waits for. */
+	readonly #keeping = new Set<Promise<void>>();
+	/** The last write, which the next waits for: ids follow the order the queue refused the entries in. */
+	#lastKept: Promise<void> = Promise.resolve();
 
 	constructor(host: TurnHost) {
 		this.#host = host;
 	}
 
-	message(caller: AgentTurnScope, to: string, text: string): string {
-		const { store, queue, logger } = this.#host.options;
+	/** What is still being written to the outbox; the shutdown drain waits until it is empty. */
+	busy(): string[] {
+		return this.#keeping.size > 0 ? ["agent messages being kept"] : [];
+	}
+
+	message(
+		caller: AgentTurnScope,
+		to: string,
+		text: string,
+		conversation?: string,
+	): string {
+		const { store, queue, logger, surfaces } = this.#host.options;
 		if (to === caller.name)
 			throw new AgentError("message_agent is for other agents, not yourself.");
 		const target = store.activeAgent(to);
 		const sender = store.activeAgent(caller.name);
-		// A turn in a room of another surface talks to the other agents' rooms there, never in Discord.
+		// The sender writes from its turn channel, to which the answer returns.
 		const parent = this.#host.turnChannel(caller);
-		const via = roomSurfaceOf(parent);
-		if (via === undefined && !target.channelId)
-			throw new AgentError(`${to} has no channel yet.`);
+		const targetChannel = messageTarget(
+			{
+				store,
+				roomSurfaces: surfaces?.roomSurfaces() ?? [],
+				latest: store.conversations.latest(target.name),
+				from: parent,
+			},
+			target,
+			conversation,
+		);
 		// Every agent turn runs through #turn, which registers its chain; a message from anywhere
 		// else would start an uncounted chain, so it is refused.
 		const chain = this.#host.chains.get(caller.session);
@@ -58,32 +78,52 @@ export class AgentMessages {
 				chainLimitReason(addressee(chain.speaker, this.#host.options.owner)),
 			);
 		chain.messages += 1;
-		const targetChannel = this.#home(target, via);
 		// The thread opens in the sender's turn channel, on its surface when that hosts threads; a
-		// surface that hosts none leaves the answer returning to the sender's room.
+		// surface that hosts none leaves the answer returning to the sender's conversation.
 		const exchange = this.#openExchange(parent, sender, target, text);
 		void queue
 			.run(targetChannel, async () =>
-				this.#deliver(sender, target, text, chain, await exchange, via),
+				this.#deliver(
+					sender,
+					target,
+					text,
+					chain,
+					await exchange,
+					targetChannel,
+					parent,
+				),
 			)
-			.catch((error: unknown) =>
+			.catch((error: unknown) => {
+				if (error instanceof HostStoppingError) {
+					// Refused before it started: the thread it opened has nothing more to hold.
+					void exchange.then((opened) => opened?.thread.close());
+					this.#keep({
+						kind: "message",
+						sender: sender.name,
+						target: target.name,
+						channel: targetChannel,
+						text,
+						origin: parent,
+						speaker: chain.speaker,
+						messages: chain.messages,
+					});
+					return;
+				}
 				logger.error(
 					{ from: sender.name, to: target.name, err: error },
 					"agent message not delivered",
-				),
-			);
+				);
+			});
 		logger.info(
-			{ from: sender.name, to: target.name, chain: chain.messages },
+			{
+				from: sender.name,
+				to: target.name,
+				channel: targetChannel,
+				chain: chain.messages,
+			},
 			"agent message queued",
 		);
-		return `Sent to "${target.displayName}". It works in its own channel; its answer comes back to you as a new turn.`;
-	}
-
-	/** The agent's own channel: its Discord channel, or its room on the surface of a room turn. */
-	#home(agent: Agent, via: string | undefined): ChannelKey {
-		return via === undefined
-			? discordKey(agent.channelId ?? "")
-			: agentRoomKey(via, agent.name);
+		return `Sent to "${target.displayName}" in its ${conversationLabel(targetChannel)}. It works there; its answer comes back to you as a new turn.`;
 	}
 
 	/**
@@ -125,10 +165,19 @@ export class AgentMessages {
 		text: string,
 		chain: Chain,
 		exchange: Exchange | undefined,
-		via: string | undefined,
+		targetChannel: ChannelKey,
+		senderChannel: ChannelKey,
 	): Promise<void> {
 		try {
-			await this.#exchange(sender, target, text, chain, exchange, via);
+			await this.#exchange(
+				sender,
+				target,
+				text,
+				chain,
+				exchange,
+				targetChannel,
+				senderChannel,
+			);
 		} finally {
 			await exchange?.thread.close();
 		}
@@ -140,10 +189,10 @@ export class AgentMessages {
 		text: string,
 		chain: Chain,
 		exchange: Exchange | undefined,
-		via: string | undefined,
+		targetChannel: ChannelKey,
+		senderChannel: ChannelKey,
 	): Promise<void> {
 		const { queue, logger } = this.#host.options;
-		const targetChannel = this.#home(target, via);
 		await this.#host.post(targetChannel, this.#host.current(sender), {
 			chunks: splitReply(
 				deliveredMessagePost(this.#host.current(target), text),
@@ -151,7 +200,7 @@ export class AgentMessages {
 		});
 		const result = await this.#host.turn(
 			target,
-			via === undefined ? homeScope(target) : roomScope(target, targetChannel),
+			scopeOf(target, targetChannel),
 			targetChannel,
 			agentMessageText(
 				this.#host.current(sender),
@@ -159,21 +208,25 @@ export class AgentMessages {
 				addressee(chain.speaker, this.#host.options.owner),
 			),
 			chain,
+			{ unattended: true },
 		);
 		const thread = exchange?.thread;
 		if (thread && !result.ok)
 			await thread.close(messages().agentNoReply(result.error.message));
-		const current = this.#host.options.store.agent(sender.name);
-		if (
-			current?.status !== "active" ||
-			(via === undefined && !current.channelId)
-		)
+		// A target with nothing to answer sends nothing back and wakes nobody.
+		if (isQuiet(result)) {
+			logger.info(
+				{ from: sender.name, to: target.name },
+				"agent message answered with nothing; no follow-up",
+			);
 			return;
-		const senderChannel = this.#home(current, via);
+		}
+		const current = this.#host.options.store.agent(sender.name);
+		if (current?.status !== "active") return;
 		// With a thread the answer goes there, leaving the sender's channel its own reply.
 		if (result.ok)
 			await this.#host
-				.post(exchange?.parent ?? senderChannel, this.#host.current(target), {
+				.post(senderChannel, this.#host.current(target), {
 					chunks: splitReply(returnedAnswerPost(result.text)),
 					...(thread ? { threadId: thread.id } : {}),
 				})
@@ -197,21 +250,159 @@ export class AgentMessages {
 		// The answer is a report back to the sender, so its turn may ask the owner on cards.
 		void queue
 			.run(senderChannel, () =>
-				this.#host.turn(
-					current,
-					via === undefined
-						? homeScope(current)
-						: roomScope(current, senderChannel),
-					senderChannel,
-					followUp,
-					chain,
-					{
-						interactive: true,
-					},
-				),
+				this.#followUp(current, senderChannel, followUp, chain),
 			)
-			.catch((error: unknown) =>
-				logger.error({ err: error }, "agent follow-up failed"),
+			.catch((error: unknown) => {
+				if (error instanceof HostStoppingError) {
+					// The sender would wait for this answer forever, so it waits in the outbox for the next start.
+					this.#keep({
+						kind: "reply",
+						sender: current.name,
+						target: target.name,
+						channel: senderChannel,
+						text: followUp,
+						speaker: chain.speaker,
+						messages: chain.messages,
+					});
+					return;
+				}
+				logger.error({ err: error }, "agent follow-up failed");
+			});
+	}
+
+	/** The sender's turn that carries the target's answer; it may ask the owner on cards, as a report back does. */
+	#followUp(sender: Agent, channel: ChannelKey, text: string, chain: Chain) {
+		return this.#host.turn(
+			sender,
+			scopeOf(sender, channel),
+			channel,
+			text,
+			chain,
+			{ interactive: true },
+		);
+	}
+
+	/** Writes an entry the queue refused to the outbox; the write is waited for by the shutdown. */
+	#keep(entry: OutboxEntry): void {
+		const { store, logger } = this.#host.options;
+		const write = this.#lastKept
+			.then(() => store.outbox.keep(entry))
+			.then(
+				() =>
+					logger.info(
+						{ kind: entry.kind, from: entry.sender, to: entry.target },
+						"agent message kept for the next start",
+					),
+				(error: unknown) =>
+					logger.error(
+						{
+							kind: entry.kind,
+							from: entry.sender,
+							to: entry.target,
+							err: error,
+						},
+						"agent message lost: not kept for the next start",
+					),
 			);
+		this.#lastKept = write;
+		this.#keeping.add(write);
+		void write.finally(() => this.#keeping.delete(write));
+	}
+
+	/**
+	 * Delivers what the last run kept, oldest first, each through the queue of the conversation it
+	 * addressed; never rejects. An entry is taken out of the outbox when its turn starts, so it runs
+	 * once even with a second replay or another host reading the same table; one the queue refuses
+	 * stays for the next start.
+	 */
+	async replay(): Promise<void> {
+		const { store, queue, logger } = this.#host.options;
+		// A failed read leaves the entries kept for the next start and does not fail this one.
+		const entries = await store.outbox.pending().catch((error: unknown) => {
+			logger.error({ err: error }, "kept agent messages not read");
+			return [];
+		});
+		if (entries.length === 0) return;
+		logger.info({ count: entries.length }, "replaying agent messages");
+		for (const entry of entries)
+			void queue
+				.run(entry.channel, () => this.#replayOne(entry))
+				.catch((error: unknown) => {
+					if (error instanceof HostStoppingError)
+						logger.info(
+							{ id: entry.id },
+							"agent message stays kept: the host is stopping",
+						);
+					else
+						logger.error(
+							{ id: entry.id, err: error },
+							"agent message not replayed",
+						);
+				});
+	}
+
+	/** The kept speaker as they stand now, like a background turn's author; undefined when gone or disabled. */
+	async #stillRunsAs(kept: Speaker): Promise<Speaker | undefined> {
+		const principals = this.#host.options.principals?.();
+		if (!principals || kept.principalId === SYSTEM_PRINCIPAL) return kept;
+		try {
+			const now = await principals.speakerFor(kept.principalId, kept.tier);
+			return { ...kept, tier: now.tier, principalId: now.principalId };
+		} catch (error) {
+			if (error instanceof IdentityError) return undefined;
+			throw error;
+		}
+	}
+
+	async #replayOne(entry: StoredOutboxEntry): Promise<void> {
+		const { store, logger } = this.#host.options;
+		if (!(await store.outbox.claim(entry.id))) return;
+		const sender = store.agent(entry.sender);
+		const target = store.agent(entry.target);
+		// An agent archived or moved to another channel since has no turn to give the entry.
+		const has = (agent: Agent | undefined, channel: ChannelKey) =>
+			agent?.status === "active" &&
+			(discordIdOf(channel) === undefined ||
+				(agent.channelId !== undefined &&
+					discordKey(agent.channelId) === channel));
+		const origin = entry.origin ?? entry.channel;
+		const intact =
+			entry.kind === "message"
+				? has(target, entry.channel) && has(sender, origin)
+				: has(sender, entry.channel);
+		if (!sender || !target || !intact) {
+			logger.warn(
+				{ id: entry.id, from: entry.sender, to: entry.target },
+				"kept agent message dropped: its agent or channel is gone",
+			);
+			return;
+		}
+		logger.info(
+			{ id: entry.id, kind: entry.kind, from: entry.sender, to: entry.target },
+			"replaying a kept agent message",
+		);
+		const speaker = await this.#stillRunsAs(entry.speaker);
+		if (!speaker) {
+			logger.warn(
+				{ id: entry.id, from: entry.sender },
+				"kept agent message dropped: its speaker may no longer run",
+			);
+			return;
+		}
+		const chain: Chain = { messages: entry.messages, speaker };
+		if (entry.kind === "reply") {
+			await this.#followUp(sender, entry.channel, entry.text, chain);
+			return;
+		}
+		// Its thread was closed when the host refused it, so the answer returns to the sender's conversation.
+		await this.#exchange(
+			sender,
+			target,
+			entry.text,
+			chain,
+			undefined,
+			entry.channel,
+			origin,
+		);
 	}
 }

package/src/core/agents/agent-outbox.ts

@@ -0,0 +1,91 @@
+import type { SQL } from "bun";
+import type { Migration } from "../db/migrations.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { Speaker } from "../speakers.ts";
+
+/**
+ * An agent message the host stopped before it could deliver. `message` is the request to the
+ * target; `reply` is the follow-up turn that carries the target's answer back to the sender. Each
+ * is kept with the chain it belonged to, so the replayed turn counts against the same limit.
+ */
+export interface OutboxEntry {
+	kind: "message" | "reply";
+	/** The agent that asked. */
+	sender: string;
+	/** The agent whose turn the entry starts. */
+	target: string;
+	/** The target's conversation: where the entry runs and posts. */
+	channel: ChannelKey;
+	/** What the turn is given: the request, or the sender's follow-up text. */
+	text: string;
+	/** For a `message`, the sender's conversation, where the answer returns. */
+	origin?: ChannelKey;
+	speaker: Speaker;
+	/** The messages the chain had sent when the entry was stored. */
+	messages: number;
+}
+
+/** A stored entry and its id, which orders the replay and makes it happen once. */
+export interface StoredOutboxEntry extends OutboxEntry {
+	id: number;
+}
+
+interface OutboxRow {
+	id: string | number;
+	payload: OutboxEntry | string;
+}
+
+/** The table of undelivered agent messages, created after the guild scoping so it carries its guild from the start. */
+export const outboxMigration = (): Migration => ({
+	name: "agent-outbox",
+	up: async (sql) => {
+		await sql`
+			CREATE TABLE IF NOT EXISTS agent_outbox (
+				id bigserial PRIMARY KEY,
+				guild_id text NOT NULL,
+				channel text NOT NULL,
+				payload jsonb NOT NULL,
+				created_at timestamptz NOT NULL DEFAULT now()
+			)`;
+		await sql`CREATE INDEX IF NOT EXISTS agent_outbox_guild ON agent_outbox (guild_id, id)`;
+	},
+});
+
+/**
+ * Agent messages and follow-ups the host refused while it stopped, kept for the next start.
+ * A row is removed by whoever claims it, so two hosts replaying the same table deliver each once.
+ */
+export class AgentOutbox {
+	readonly #sql: SQL;
+	readonly #guild: string;
+
+	constructor(sql: SQL, guildId: string) {
+		this.#sql = sql;
+		this.#guild = guildId;
+	}
+
+	async keep(entry: OutboxEntry): Promise<void> {
+		await this.#sql`
+			INSERT INTO agent_outbox (guild_id, channel, payload)
+			VALUES (${this.#guild}, ${entry.channel}, ${JSON.stringify(entry)}::jsonb)`;
+	}
+
+	/** Every kept entry, oldest first. */
+	async pending(): Promise<StoredOutboxEntry[]> {
+		const rows: OutboxRow[] = await this.#sql`
+			SELECT id, payload FROM agent_outbox WHERE guild_id = ${this.#guild} ORDER BY id`;
+		return rows.map((row) => ({
+			...(typeof row.payload === "string"
+				? (JSON.parse(row.payload) as OutboxEntry)
+				: row.payload),
+			id: Number(row.id),
+		}));
+	}
+
+	/** Takes the entry out; false when another host or an earlier call already did. */
+	async claim(id: number): Promise<boolean> {
+		const rows: { id: string | number }[] = await this.#sql`
+			DELETE FROM agent_outbox WHERE guild_id = ${this.#guild} AND id = ${id} RETURNING id`;
+		return rows.length > 0;
+	}
+}

package/src/core/agents/agent-prompt.ts

@@ -1,3 +1,5 @@
+import { parseChannelKey, type SurfacePort } from "../contract/surface.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
 import { messages } from "../i18n/index.ts";
 import { type OwnerIdentity, ownerWords } from "../identity.ts";
 import type { AgentTools } from "../plugin.ts";
@@ -28,6 +30,8 @@ export function agentSystemPrompt(input: {
 	images?: boolean;
 	/** "chat-only": the agent has no shell, file tools or workspace, and the prompt says so. Default "full". */
 	agentTools?: AgentTools;
+	/** Where this conversation is, and the other surfaces the agent has places on. */
+	surface?: { label: string; key: string; others: readonly string[] };
 }): string {
 	const { agent, coordinator, shared, workDir, owner, shellUser, group } =
 		input;
@@ -37,7 +41,7 @@ export function agentSystemPrompt(input: {
 	const guest = input.speaker && input.speaker.tier !== "owner";
 	const parts = [
 		(guest && input.guestShared) || shared,
-		`You are "${agent.displayName}" (agent name \`${agent.name}\`), one of ${o.name}'s agents in ${o.his} Discord agent server. Each agent owns one channel and one conversation; you all share ${o.his} tools and ${o.his} memory.`,
+		`You are "${agent.displayName}" (agent name \`${agent.name}\`), one of ${o.name}'s agents in ${o.his} agent server.${placeText(input.surface)} Each agent owns one channel and one conversation; you all share ${o.his} tools and ${o.his} memory.`,
 		roleText(agent, coordinator, who),
 		`The team: agent_list shows every agent and group; agent_get and agent_update read and improve any agent's prompt, display name, model, and thinking level, yours included; agent_create adds an agent with its own channel; agent_avatar changes an agent's look (class, colors, parts); schedule_list with agent reads another agent's schedules. A message marked as coming from another agent is that agent speaking, not ${w.name}; only ${w.name} approves held actions.`,
 		input.agentTools === "chat-only"
@@ -62,6 +66,19 @@ export function agentSystemPrompt(input: {
 	return parts.join("\n\n");
 }
 
+/** Names the surface of this conversation, and the others the agent has places on. */
+function placeText(
+	surface:
+		| NonNullable<Parameters<typeof agentSystemPrompt>[0]["surface"]>
+		| undefined,
+): string {
+	if (!surface) return "";
+	const others = surface.others.length
+		? ` You also have places on ${surface.others.join(", ")}.`
+		: "";
+	return ` This conversation is in ${surface.label} (${surface.key}).${others}`;
+}
+
 /**
  * Says whom the turn is for when it is not the owner, after every operator text that names the
  * owner, so those texts read as the owner's and this one decides who is addressed.
@@ -169,3 +186,25 @@ export function chainLimitReason(who: OwnerIdentity): string {
 	const o = ownerWords(who);
 	return `This chain of agent messages has reached 8 messages without ${o.name} in between, so it is stopped. Tell ${o.him} what was done and ask whether to continue.`;
 }
+
+/**
+ * Where a turn's conversation is: the surface of the turn's conversation (`home`: the agent's own
+ * channel or room, or the group's in a group round), named by its `label`, and the other surfaces the agents have places on, Discord when the team has
+ * channels and each surface that hosts rooms.
+ */
+export function placeOf(
+	home: ChannelKey,
+	surfaces: Pick<SurfacePort, "of" | "roomSurfaces"> | undefined,
+	hasDiscord: boolean,
+): { surface: { label: string; key: string; others: readonly string[] } } {
+	const prefix = parseChannelKey(home).surface;
+	const label = (name: string) =>
+		surfaces?.of(`${name}:`)?.label ?? (name === "discord" ? "Discord" : name);
+	const names = [
+		...(hasDiscord ? ["discord"] : []),
+		...(surfaces?.roomSurfaces() ?? []),
+	].filter((n, i, all) => n !== prefix && all.indexOf(n) === i);
+	return {
+		surface: { label: label(prefix), key: prefix, others: names.map(label) },
+	};
+}

package/src/core/agents/agent-schema.ts

@@ -3,6 +3,8 @@ import { scopeToGuild } from "../db/guild-scope.ts";
 import type { Migration } from "../db/migrations.ts";
 import type { ThinkingLevel } from "../models.ts";
 import { promptHistoryMigration } from "../modules/prompts/prompt-history.ts";
+import { AgentConversations } from "./agent-conversations.ts";
+import { outboxMigration } from "./agent-outbox.ts";
 import type { Agent, AgentGroup, AgentStatus } from "./agent-rules.ts";
 
 export interface AgentRow {
@@ -136,5 +138,9 @@ export function agentMigrations(guildId: string): Migration[] {
 		},
 		// The change history of the agents' prompts; the prompts plugin creates the same table for its documents.
 		promptHistoryMigration("agent-prompt-history"),
+		// Agent messages the host refused while it stopped, replayed at the next start.
+		outboxMigration(),
+		// Where each agent last ran a turn, so a message to it finds that conversation after a restart.
+		AgentConversations.migration,
 	];
 }

package/src/core/agents/agent-store.ts

@@ -9,6 +9,8 @@ import {
 } from "../modules/prompts/prompt-history.ts";
 import type { AgentDirectory } from "../services.ts";
 import { AgentBook } from "./agent-book.ts";
+import { AgentConversations } from "./agent-conversations.ts";
+import { AgentOutbox } from "./agent-outbox.ts";
 import {
 	type Agent,
 	type AgentGroup,
@@ -68,14 +70,24 @@ export class PgAgentStore extends AgentBook implements AgentDirectory {
 	readonly #statements: AgentStatements;
 	readonly #messages: GroupMessages;
 	readonly #prompts: PromptHistory;
+	/** Agent messages the host stopped before delivering them. */
+	readonly outbox: AgentOutbox;
+	/** The conversation each agent last ran a turn in. */
+	readonly conversations: AgentConversations;
 
-	private constructor(sql: SQL, guildId: string) {
+	private constructor(
+		sql: SQL,
+		guildId: string,
+		conversations: AgentConversations,
+	) {
 		super();
+		this.conversations = conversations;
 		this.#sql = sql;
 		this.#guild = guildId;
 		this.#statements = new AgentStatements(sql, guildId);
 		this.#messages = new GroupMessages(sql, guildId);
 		this.#prompts = new PromptHistory(sql, guildId);
+		this.outbox = new AgentOutbox(sql, guildId);
 	}
 
 	/** The store's tables; the host runs this before any store attaches. */
@@ -88,9 +100,16 @@ export class PgAgentStore extends AgentBook implements AgentDirectory {
 
 	/** The store over the host's migrated pool, holding the rows of one guild. */
 	static async attach(sql: SQL, guildId: string): Promise<PgAgentStore> {
-		const store = new PgAgentStore(sql, guildId);
 		// `Roundtable.check()` has no database to read the rows from: the store starts empty.
-		if (!isCheckDatabase(sql)) await store.#reload();
+		const checking = isCheckDatabase(sql);
+		const store = new PgAgentStore(
+			sql,
+			guildId,
+			checking
+				? AgentConversations.memory()
+				: await AgentConversations.load(sql, guildId),
+		);
+		if (!checking) await store.#reload();
 		return store;
 	}