pi-roundtable 0.1.0

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

@@ -0,0 +1,99 @@
+import type { SQL } from "bun";
+import type { AgentGroup, Backlog, GroupMessage } from "./agent-rules.ts";
+
+interface MessageRow {
+	id: string | number;
+	author: string;
+	author_name: string;
+	text: string;
+	created_at: Date;
+}
+
+const toMessage = (row: MessageRow): GroupMessage => ({
+	id: Number(row.id),
+	author: row.author,
+	authorName: row.author_name,
+	text: row.text,
+	at: row.created_at,
+});
+
+/** A guild's group messages and each member's cursor into them. */
+export class GroupMessages {
+	readonly #sql: SQL;
+	readonly #guild: string;
+
+	constructor(sql: SQL, guildId: string) {
+		this.#sql = sql;
+		this.#guild = guildId;
+	}
+
+	async append(
+		group: string,
+		message: { author: string; authorName: string; text: string },
+	): Promise<number> {
+		const rows: { id: string | number }[] = await this.#sql`
+			INSERT INTO agent_group_messages (guild_id, group_name, author, author_name, text)
+			VALUES (${this.#guild}, ${group}, ${message.author}, ${message.authorName}, ${message.text})
+			RETURNING id`;
+		return Number(rows[0]?.id);
+	}
+
+	/** The group's newest messages, oldest first. */
+	async recent(group: string, limit: number): Promise<GroupMessage[]> {
+		const rows: MessageRow[] = await this.#sql`
+			SELECT id, author, author_name, text, created_at FROM agent_group_messages
+			WHERE guild_id = ${this.#guild} AND group_name = ${group} ORDER BY id DESC LIMIT ${limit}`;
+		return rows.reverse().map(toMessage);
+	}
+
+	/** Group messages the member has not received yet, its own excluded; the newest `limit` are carried. */
+	async backlog(group: string, agent: string, limit: number): Promise<Backlog> {
+		const cursor = await this.#cursor(group, agent);
+		const rows: MessageRow[] = await this.#sql`
+			SELECT id, author, author_name, text, created_at FROM agent_group_messages
+			WHERE guild_id = ${this.#guild} AND group_name = ${group} AND id > ${cursor}
+			ORDER BY id`;
+		const waiting = rows.map(toMessage);
+		const others = waiting.filter((m) => m.author !== agent);
+		const carried = others.slice(-limit);
+		return {
+			messages: carried,
+			skipped: others.length - carried.length,
+			lastId: waiting.at(-1)?.id,
+		};
+	}
+
+	async advanceCursor(
+		group: string,
+		agent: string,
+		lastId: number,
+	): Promise<void> {
+		await this.#sql`
+			INSERT INTO agent_group_cursors (guild_id, group_name, agent_name, last_id)
+			VALUES (${this.#guild}, ${group}, ${agent}, ${lastId})
+			ON CONFLICT (guild_id, group_name, agent_name)
+			DO UPDATE SET last_id = GREATEST(agent_group_cursors.last_id, EXCLUDED.last_id)`;
+	}
+
+	/** Marks every message so far as received by every member, for a group started over. */
+	async catchUp(group: AgentGroup): Promise<void> {
+		const rows: { id: string | number | null }[] = await this.#sql`
+			SELECT max(id) AS id FROM agent_group_messages
+			WHERE guild_id = ${this.#guild} AND group_name = ${group.name}`;
+		const last = rows[0]?.id;
+		if (last === null || last === undefined) return;
+		for (const member of group.members)
+			await this.advanceCursor(group.name, member, Number(last));
+	}
+
+	/**
+	 * A member's cursor; one that joined late starts at the messages before it joined, so it
+	 * catches up on the group's recent history.
+	 */
+	async #cursor(group: string, agent: string): Promise<number> {
+		const rows: { last_id: string | number }[] = await this.#sql`
+			SELECT last_id FROM agent_group_cursors
+			WHERE guild_id = ${this.#guild} AND group_name = ${group} AND agent_name = ${agent}`;
+		return rows[0] ? Number(rows[0].last_id) : 0;
+	}
+}

package/src/core/agents/group-round.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from "bun:test";
+import pino from "pino";
+import type { YesNoQuestion } from "../domain/ports.ts";
+import { TEST_OWNER as OWNER } from "../testing/owner.ts";
+import type { Agent } from "./agent-store.ts";
+import { mentionedMembers, planRound, RelevanceScorer } from "./group-round.ts";
+
+const agent = (name: string, displayName: string): Agent => ({
+	name,
+	displayName,
+	prompt: `You are ${displayName}.`,
+	avatarPrompt: "",
+	status: "active",
+});
+const members = [
+	agent("coordinator", "Координатор"),
+	agent("infra", "Infra"),
+	agent("doctor", "Bot Доктор"),
+];
+const logger = pino({ level: "silent" });
+
+describe("mentionedMembers", () => {
+	test("matches display names and names, ignoring case", () => {
+		expect(mentionedMembers("@Bot Доктор what do you think", members)).toEqual([
+			"doctor",
+		]);
+		expect(
+			mentionedMembers("@infra and @Координатор take a look", members),
+		).toEqual(["coordinator", "infra"]);
+	});
+
+	test("does not match a longer word", () => {
+		expect(mentionedMembers("@infrastructure", members)).toEqual([]);
+		expect(mentionedMembers("infra hello", members)).toEqual([]);
+	});
+});
+
+describe("planRound", () => {
+	const names = members.map((m) => m.name);
+
+	test("members above the threshold answer, most relevant last", () => {
+		expect(
+			planRound({
+				members: names,
+				host: "coordinator",
+				scores: { coordinator: 0.6, infra: 0.95, doctor: 0.2 },
+				forced: new Set(),
+			}),
+		).toEqual(["coordinator", "infra"]);
+	});
+
+	test("a forced member answers whatever its score, in score order", () => {
+		expect(
+			planRound({
+				members: names,
+				host: "coordinator",
+				scores: { coordinator: 0.1, infra: 0.9, doctor: 0.05 },
+				forced: new Set(["doctor"]),
+			}),
+		).toEqual(["doctor", "infra"]);
+	});
+
+	test("ties keep group order", () => {
+		expect(
+			planRound({
+				members: names,
+				host: "coordinator",
+				scores: { coordinator: 0.7, infra: 0.7, doctor: 0.7 },
+				forced: new Set(),
+			}),
+		).toEqual(names);
+	});
+
+	test("with nobody qualifying the host answers alone", () => {
+		expect(
+			planRound({
+				members: names,
+				host: "infra",
+				scores: { coordinator: 0.1, infra: 0.2, doctor: 0.3 },
+				forced: new Set(),
+			}),
+		).toEqual(["infra"]);
+	});
+
+	test("without scores only forced members answer, or the host", () => {
+		expect(
+			planRound({
+				members: names,
+				host: "coordinator",
+				scores: undefined,
+				forced: new Set(["doctor"]),
+			}),
+		).toEqual(["doctor"]);
+		expect(
+			planRound({
+				members: names,
+				host: "coordinator",
+				scores: undefined,
+				forced: new Set(),
+			}),
+		).toEqual(["coordinator"]);
+	});
+});
+
+describe("RelevanceScorer", () => {
+	test("asks one question per member in one request and maps the answers back", async () => {
+		const asked: Record<string, YesNoQuestion>[] = [];
+		const scorer = new RelevanceScorer(
+			{
+				askYesNo: async (_state, questions) => {
+					asked.push(questions);
+					return { m_coordinator: 0.3, m_infra: 0.9, m_doctor: 0.1 };
+				},
+			},
+			logger,
+			OWNER,
+		);
+		expect(await scorer.score(members, [], "the disk is almost full")).toEqual({
+			coordinator: 0.3,
+			infra: 0.9,
+			doctor: 0.1,
+		});
+		expect(asked).toHaveLength(1);
+		expect(Object.keys(asked[0] ?? {})).toEqual([
+			"m_coordinator",
+			"m_infra",
+			"m_doctor",
+		]);
+	});
+
+	test("a failed request yields no scores", async () => {
+		const scorer = new RelevanceScorer(
+			{
+				askYesNo: async () => {
+					throw new Error("down");
+				},
+			},
+			logger,
+			OWNER,
+		);
+		expect(await scorer.score(members, [], "hi")).toBeUndefined();
+	});
+});

package/src/core/agents/group-round.ts

@@ -0,0 +1,117 @@
+import type { Judge } from "../contract/providers.ts";
+import { type OwnerIdentity, ownerWords } from "../identity.ts";
+import type { Logger } from "../log.ts";
+import type { Agent, GroupMessage } from "./agent-store.ts";
+
+/** Members at or above this relevance answer an owner message nobody is named in. */
+export const RELEVANCE_THRESHOLD = 0.5;
+/** Replies one round may hold, handoffs included (spec behavior 29). */
+export const MAX_ROUND_REPLIES = 8;
+/** Group messages the scorer reads before the new one. */
+export const RECENT_FOR_SCORING = 12;
+const SCORING_TEXT_CHARS = 1_500;
+const PROMPT_CHARS_FOR_SCORING = 1_200;
+
+const escapeRegExp = (value: string) =>
+	value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Members a text names with `@display name` or `@name`, in group order. */
+export function mentionedMembers(
+	text: string,
+	members: readonly Agent[],
+): string[] {
+	return members
+		.filter((member) =>
+			[member.displayName, member.name].some((label) =>
+				new RegExp(`@${escapeRegExp(label)}(?![\\p{L}\\p{N}_-])`, "iu").test(
+					text,
+				),
+			),
+		)
+		.map((member) => member.name);
+}
+
+/**
+ * Who answers, in speaking order: members at or above the threshold and every forced member,
+ * lowest relevance first so the most relevant speaks last; ties keep group order. Without
+ * scores only the forced members answer; with nobody at all, the host answers alone.
+ */
+export function planRound(input: {
+	members: readonly string[];
+	host: string;
+	scores: Readonly<Record<string, number>> | undefined;
+	forced: ReadonlySet<string>;
+	threshold?: number;
+}): string[] {
+	const { members, host, scores, forced } = input;
+	const threshold = input.threshold ?? RELEVANCE_THRESHOLD;
+	const chosen = members.filter(
+		(name) => forced.has(name) || (scores?.[name] ?? 0) >= threshold,
+	);
+	if (chosen.length === 0) return [host];
+	return chosen
+		.map((name, index) => ({ name, index, score: scores?.[name] ?? 0 }))
+		.sort((a, b) => a.score - b.score || a.index - b.index)
+		.map((entry) => entry.name);
+}
+
+/** One judge request with one yes-or-no question per member: should it answer this message? */
+export class RelevanceScorer {
+	readonly #judge: Pick<Judge, "askYesNo">;
+	readonly #logger: Logger;
+	readonly #owner: OwnerIdentity;
+
+	constructor(
+		judge: Pick<Judge, "askYesNo">,
+		logger: Logger,
+		owner: OwnerIdentity,
+	) {
+		this.#judge = judge;
+		this.#logger = logger;
+		this.#owner = owner;
+	}
+
+	/** Each member's relevance from 0 to 1; undefined when the judge failed. */
+	async score(
+		members: readonly Agent[],
+		recent: readonly GroupMessage[],
+		text: string,
+	): Promise<Record<string, number> | undefined> {
+		const key = (name: string) => `m_${name.replaceAll("-", "_")}`;
+		const questions = Object.fromEntries(
+			members.map((member) => [
+				key(member.name),
+				{
+					type: "yesno" as const,
+					instructions: `Should the agent "${member.displayName}" answer the owner's newest message in this group chat? Its role:\n${member.prompt.slice(0, PROMPT_CHARS_FOR_SCORING)}`,
+					criteria: {
+						true: "The message is about this agent's role, asks for knowledge or work it owns, or its view would add something the others would not.",
+						false:
+							"The message is outside this agent's role, or another member clearly owns it and this agent would add nothing.",
+					},
+				},
+			]),
+		);
+		const o = ownerWords(this.#owner);
+		const state = {
+			task: `A group chat between the owner, ${o.name}, and ${o.his} agents. Decide who should answer ${o.his} newest message.`,
+			members: members.map((m) => ({ name: m.displayName, id: m.name })),
+			recent: recent.slice(-RECENT_FOR_SCORING).map((m) => ({
+				from: m.authorName,
+				text: m.text.slice(0, SCORING_TEXT_CHARS),
+			})),
+			newest: text.slice(0, SCORING_TEXT_CHARS),
+		};
+		try {
+			const answers = await this.#judge.askYesNo(state, questions);
+			const scores = Object.fromEntries(
+				members.map((m) => [m.name, answers[key(m.name)] ?? 0]),
+			);
+			this.#logger.info({ scores }, "group relevance scored");
+			return scores;
+		} catch (error) {
+			this.#logger.warn({ err: error }, "group relevance scoring failed");
+			return undefined;
+		}
+	}
+}

package/src/core/agents/group-turns.ts

@@ -0,0 +1,132 @@
+import type { TurnAttachments } from "../domain/attachment.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import { AgentError } from "../domain/errors.ts";
+import { messages } from "../i18n/index.ts";
+import type { Speaker } from "../speakers.ts";
+import { groupTurnText } from "./agent-prompt.ts";
+import type { Agent } from "./agent-store.ts";
+import {
+	MAX_ROUND_REPLIES,
+	mentionedMembers,
+	planRound,
+	RECENT_FOR_SCORING,
+} from "./group-round.ts";
+import { channelIdOf, groupScope, groupSessionKey } from "./team-keys.ts";
+import { BACKLOG_LIMIT, type Chain, type TurnHost } from "./team-turn-types.ts";
+
+/** A group channel's rounds: scoring, then the chosen members answer one at a time. */
+export class GroupTurns {
+	readonly #host: TurnHost;
+
+	constructor(host: TurnHost) {
+		this.#host = host;
+	}
+
+	/**
+	 * One owner message in a group channel: scored, then answered by the chosen members one at
+	 * a time, each seeing every group message since its last turn. Call inside the queue.
+	 */
+	async answerGroup(
+		channel: ChannelKey,
+		speaker: Speaker,
+		text: string,
+		replyText: string,
+		attachments: TurnAttachments,
+		repliedToName: string | undefined,
+	): Promise<void> {
+		const { store, scorer, confirmations, logger } = this.#host.options;
+		const runtime = this.#host.options.runtime();
+		const group = store.groupByChannel(channelIdOf(channel));
+		if (!group) throw new AgentError(`no group owns ${channel}`);
+		const members = group.members
+			.map((name) => store.agent(name))
+			.filter((m): m is Agent => m?.status === "active");
+		const recent = await store.recentGroupMessages(
+			group.name,
+			RECENT_FOR_SCORING,
+		);
+		await store.appendGroupMessage(group.name, {
+			author: speaker.tier === "owner" ? "owner" : `human:${speaker.id}`,
+			authorName:
+				speaker.tier === "owner" ? this.#host.options.owner.name : speaker.name,
+			text,
+		});
+
+		const forced = new Set(mentionedMembers(replyText, members));
+		const repliedTo = members.find((m) => m.displayName === repliedToName);
+		if (repliedTo) forced.add(repliedTo.name);
+		const approvals = new Map<string, boolean>();
+		for (const member of members) {
+			const pending = await runtime.heldActions(
+				groupSessionKey(group, member.name),
+			);
+			// Only a speaker whose tier holds the held tools may approve or wake a seat for them.
+			if (!pending || !this.#host.mayApprove(speaker, pending)) continue;
+			forced.add(member.name);
+			approvals.set(
+				member.name,
+				await confirmations.approves(pending, replyText),
+			);
+		}
+		const scores =
+			forced.size === members.length
+				? undefined
+				: await scorer.score(members, recent, text);
+		const order = planRound({
+			members: members.map((m) => m.name),
+			host: members.some((m) => m.name === group.host)
+				? group.host
+				: (members[0]?.name ?? group.host),
+			scores,
+			forced,
+		});
+		logger.info({ group: group.name, scores, order }, "group round planned");
+
+		const chain: Chain = { messages: 0, speaker };
+		const queued = [...order];
+		const spoken = new Set<string>();
+		let last: Agent | undefined;
+		let replies = 0;
+		while (queued.length > 0 && replies < MAX_ROUND_REPLIES) {
+			// A member may archive the group during the round.
+			if (store.group(group.name)?.status !== "active") return;
+			const name = queued.shift() as string;
+			const member = store.agent(name);
+			if (member?.status !== "active") continue;
+			const first = !spoken.has(name);
+			spoken.add(name);
+			const backlog = await store.backlog(group.name, name, BACKLOG_LIMIT);
+			// Delivered once the session has the text, so a message never comes twice.
+			if (backlog.lastId !== undefined)
+				await store.advanceCursor(group.name, name, backlog.lastId);
+			const result = await this.#host.turn(
+				member,
+				groupScope(member, group),
+				channel,
+				groupTurnText(group, member, backlog),
+				chain,
+				first
+					? {
+							attachments,
+							interactive: true,
+							...(approvals.get(name) ? { confirmed: true } : {}),
+						}
+					: { interactive: true },
+			);
+			replies += 1;
+			last = member;
+			if (!result.ok) continue;
+			await store.appendGroupMessage(group.name, {
+				author: name,
+				authorName: this.#host.current(member).displayName,
+				text: result.text,
+			});
+			for (const handoff of mentionedMembers(result.text, members))
+				if (handoff !== name && !queued.includes(handoff)) queued.push(handoff);
+		}
+		if (queued.length > 0 && last)
+			await this.#host.post(channel, this.#host.current(last), {
+				chunks: [messages().roundLimitNotice],
+			});
+	}
+}

package/src/core/agents/owner-identity.test.ts

@@ -0,0 +1,172 @@
+import { expect, test } from "bun:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { InboundMessage } from "../domain/conversation.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import { withReference } from "../routing/message-text.ts";
+import {
+	answerText,
+	askUserExtension,
+} from "../runtime/extensions/ask-user.ts";
+import {
+	ConfirmationGate,
+	confirmedTurnText,
+} from "../runtime/extensions/confirmation-gate.ts";
+import { PromptSlot } from "../runtime/prompt-slot.ts";
+import { addressee, type Speaker, THE_SPEAKER } from "../speakers.ts";
+import {
+	agentFailureText,
+	agentMessageText,
+	agentReplyText,
+	agentSystemPrompt,
+	chainLimitReason,
+	openingTaskText,
+} from "./agent-prompt.ts";
+import type { Agent } from "./agent-store.ts";
+
+const ALICE: OwnerIdentity = {
+	name: "Alice",
+	pronouns: { subject: "she", object: "her", possessive: "her" },
+};
+
+const agent: Agent = {
+	name: "scout",
+	displayName: "Scout",
+	prompt: "Scout things.",
+	avatarPrompt: "",
+	channelId: "5",
+	status: "active",
+};
+const coordinator: Agent = {
+	...agent,
+	name: "coordinator",
+	displayName: "Coordinator",
+	channelId: "1",
+};
+
+/** Every text these modules show a model, built for an owner who is not the test default. */
+function texts(): string[] {
+	const gate = new ConfirmationGate(() => "delete the task", ALICE);
+	return [
+		agentSystemPrompt({
+			agent,
+			coordinator,
+			shared: "",
+			workDir: "/w",
+			owner: ALICE,
+			shellUser: "alice-bot",
+		}),
+		agentSystemPrompt({
+			agent: coordinator,
+			coordinator,
+			shared: "",
+			workDir: "/w",
+			owner: ALICE,
+			shellUser: "alice-bot",
+		}),
+		agentMessageText(agent, "x", ALICE),
+		agentReplyText(ALICE, agent, "x"),
+		agentFailureText(ALICE, agent, "r"),
+		openingTaskText(undefined, "t", ALICE),
+		chainLimitReason(ALICE),
+		answerText(undefined, ALICE),
+		answerText({ choices: ["A"], text: "b" }, ALICE),
+		gate.hold("any", {}) ?? "",
+		confirmedTurnText(
+			{ profile: "general", heldAt: new Date(0), calls: [] },
+			"ok",
+			ALICE,
+		),
+		withReference(
+			{
+				text: "look",
+				forwarded: { channelMention: "<#2>", url: "https://x", text: "f" },
+			} as InboundMessage,
+			ALICE,
+		),
+	];
+}
+
+test("prompts name the configured owner and shell user, never the default's", () => {
+	const all = texts().join("\n");
+	expect(all).not.toContain("Riley");
+	expect(all).not.toContain("mcops");
+	expect(all).not.toMatch(/\b(he|him|his|He|His)\b/);
+	expect(all).toContain("Alice");
+	expect(all).toContain("alice-bot");
+});
+
+const BOB: Speaker = { id: "100000000000000007", name: "Bob", tier: "member" };
+const promptFor = (speaker?: Speaker) =>
+	agentSystemPrompt({
+		agent,
+		coordinator,
+		shared: "",
+		workDir: "/w",
+		owner: ALICE,
+		shellUser: "alice-bot",
+		...(speaker ? { speaker } : {}),
+	});
+
+test("an owner-tier speaker gets the owner's prompts unchanged", () => {
+	const owner: Speaker = { id: "1", name: "Alice", tier: "owner" };
+	expect(promptFor(owner)).toBe(promptFor());
+	expect(openingTaskText(undefined, "t", addressee(owner, ALICE))).toBe(
+		openingTaskText(undefined, "t", ALICE),
+	);
+});
+
+test("a member's turn addresses the member and says whose memory and approvals apply", () => {
+	const prompt = promptFor(BOB);
+	expect(prompt).toContain("only Bob approves held actions");
+	expect(prompt).toContain("held for Bob's confirmation");
+	expect(prompt).toContain(
+		"You are talking with Bob (Discord user 100000000000000007), who speaks at the member tier",
+	);
+	expect(prompt).toContain("Your memory is Bob's own, not Alice's");
+	expect(prompt).not.toContain("only Alice approves");
+	const bob = addressee(BOB, ALICE);
+	expect(chainLimitReason(bob)).toContain("without Bob in between");
+	expect(agentMessageText(agent, "x", bob)).toContain("not from Bob");
+	expect(gateHold(bob)).toContain("Held for Bob's confirmation");
+	expect(answerText(undefined, bob)).toContain("Bob did not answer");
+});
+
+function gateHold(who: OwnerIdentity): string {
+	const gate = new ConfirmationGate(() => "delete the task", ALICE);
+	gate.beginTurn("general", false, who);
+	return gate.hold("any", {}) ?? "";
+}
+
+test("a tool description in a shared session names the speaker, not the owner", () => {
+	let description = "";
+	askUserExtension(
+		new PromptSlot(),
+		THE_SPEAKER,
+	)({
+		registerTool: (tool: { description: string }) => {
+			description = tool.description;
+		},
+	} as unknown as ExtensionAPI);
+	expect(description).toContain("Ask the speaker a question");
+	expect(description).toContain("wait for the speaker's answer");
+	expect(description).toContain("The speaker has 30 minutes");
+	expect(description).not.toContain("Alice");
+});
+
+test("a speaker who is not the owner gets the guest's shared prompt, the owner the owner's", () => {
+	const prompt = (speaker?: Speaker) =>
+		agentSystemPrompt({
+			agent,
+			coordinator,
+			shared: "For the owner.",
+			guestShared: "For guests.",
+			workDir: "/w",
+			owner: ALICE,
+			shellUser: "alice-bot",
+			...(speaker ? { speaker } : {}),
+		});
+	expect(prompt().startsWith("For the owner.")).toBe(true);
+	expect(prompt({ id: "1", name: "Alice", tier: "owner" })).toBe(prompt());
+	expect(prompt(BOB).startsWith("For guests.")).toBe(true);
+	expect(prompt(BOB)).not.toContain("For the owner.");
+});