pi-roundtable 0.1.0

package/src/core/agents/agent-claim.test.ts

@@ -0,0 +1,142 @@
+import { expect, test } from "bun:test";
+import type { InboundMessage } from "../contract/channels.ts";
+import { silentLogger } from "../log.ts";
+import { type Speaker, speakerPolicy } from "../speakers.ts";
+import { TEST_OWNER } from "../testing/owner.ts";
+import { agentClaim } from "./agent-claim.ts";
+
+const OWNER = "100000000000000001";
+const ADMIN = "100000000000000002";
+const STRANGER = "100000000000000009";
+const ROLE = "200000000000000001";
+
+function setup() {
+	const answered: { kind: string; speaker: Speaker; text: string }[] = [];
+	const team = {
+		guildId: "1",
+		owns: (channel: string) =>
+			channel === "discord:10"
+				? ("agent" as const)
+				: channel === "discord:20"
+					? ("group" as const)
+					: undefined,
+		answerOwner: async (_c: string, speaker: Speaker, text: string) => {
+			answered.push({ kind: "agent", speaker, text });
+			return { ok: true as const, text: "" };
+		},
+		answerGroup: async (_c: string, speaker: Speaker, text: string) => {
+			answered.push({ kind: "group", speaker, text });
+		},
+		answerBackground: async (_c: string, speaker: Speaker, text: string) => {
+			answered.push({ kind: "background", speaker, text });
+			return { ok: true as const, text: "" };
+		},
+		startFresh: async () => {},
+	};
+	const claim = agentClaim({
+		owner: TEST_OWNER,
+		speakers: speakerPolicy({
+			owners: [OWNER],
+			admins: { users: [ADMIN] },
+			members: { roles: [ROLE] },
+		}),
+		// biome-ignore lint/suspicious/noExplicitAny: a recording stand-in for the team
+		team: team as any,
+		runtime: { steer: async () => false },
+		surface: { react: async () => {}, unreact: async () => {} },
+		attachmentDir: () => "/tmp",
+		logger: silentLogger(),
+	});
+	return { claim, answered };
+}
+
+const message = (
+	authorId: string,
+	channel: `${string}:${string}`,
+	extra: Partial<InboundMessage> = {},
+): InboundMessage => ({
+	channel,
+	messageId: "m1",
+	authorId,
+	authorName: `name-${authorId.slice(-1)}`,
+	authorIsBot: false,
+	isDirect: false,
+	guildId: "1",
+	mentionsBot: false,
+	repliesToBot: false,
+	text: "hello",
+	attachments: [],
+	...extra,
+});
+
+test("the owner, an admin, and a member by role are each answered as themselves", async () => {
+	const { claim, answered } = setup();
+	for (const [id, roles] of [
+		[OWNER, []],
+		[ADMIN, []],
+		[STRANGER, [ROLE]],
+	] as const) {
+		const admission = claim.admit(
+			message(id, "discord:10", { authorRoleIds: roles }),
+		);
+		if (admission?.kind !== "turn") throw new Error("expected a turn");
+		await admission.run();
+	}
+	expect(answered.map((a) => a.speaker.tier)).toEqual([
+		"owner",
+		"admin",
+		"member",
+	]);
+	expect(answered[1]?.speaker).toEqual({
+		id: ADMIN,
+		name: "name-2",
+		tier: "admin",
+	});
+});
+
+test("a turn in an agent's channel names a speaker who is not the owner, and the owner's stays plain", async () => {
+	const { claim, answered } = setup();
+	for (const id of [OWNER, ADMIN]) {
+		const admission = claim.admit(message(id, "discord:10"));
+		if (admission?.kind !== "turn") throw new Error("expected a turn");
+		await admission.run();
+	}
+	expect(answered[0]?.text).toBe("hello");
+	expect(answered[1]?.text).toBe(
+		"(Message from name-2, at the admin tier.)\n\nhello",
+	);
+});
+
+test("an author the policy does not name gets no turn, in an agent or a group channel", () => {
+	const { claim } = setup();
+	expect(claim.admit(message(STRANGER, "discord:10"))).toBeUndefined();
+	expect(claim.admit(message(STRANGER, "discord:20"))).toBeUndefined();
+	expect(
+		claim.admit(message(OWNER, "discord:10", { authorIsBot: true })),
+	).toBeUndefined();
+});
+
+test("a group message carries its speaker", async () => {
+	const { claim, answered } = setup();
+	const admission = claim.admit(message(ADMIN, "discord:20"));
+	if (admission?.kind !== "turn") throw new Error("expected a turn");
+	await admission.run();
+	expect(answered[0]).toMatchObject({
+		kind: "group",
+		speaker: { tier: "admin" },
+	});
+});
+
+test("a background turn runs at its creator's tier, the owner's when a person set none", async () => {
+	const { claim, answered } = setup();
+	const turn = {
+		channel: "discord:10" as const,
+		mode: "owner" as const,
+		author: { id: ADMIN, name: "n" },
+		turnId: "t",
+		text: "go",
+	};
+	await claim.background?.({ ...turn, tier: "admin" });
+	await claim.background?.(turn);
+	expect(answered.map((a) => a.speaker.tier)).toEqual(["admin", "owner"]);
+});

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

@@ -0,0 +1,170 @@
+import { attachmentsOf } from "../attachments/turn-attachments.ts";
+import type {
+	Admission,
+	ChannelClaim,
+	InboundMessage,
+} from "../contract/channels.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { AgentRuntime, ChatSurface } from "../domain/ports.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import type { Logger } from "../log.ts";
+import { withReference } from "../routing/message-text.ts";
+import { outcome } from "../routing/settle-turn.ts";
+import { addressee, attributed, type SpeakerPolicy } from "../speakers.ts";
+import type { AgentTeam } from "./agent-team.ts";
+
+/**
+ * The agent server outranks every other claim, and its guild's other channels stay silent even
+ * when party mode or a mention would answer there. It becomes the core's reserved branch once
+ * the team moves into the core (pi-roundtable batch 7).
+ */
+export const AGENT_SERVER_PRIORITY = 100;
+
+export interface AgentClaimOptions {
+	/** The owner, as forwarded messages name them. */
+	owner: OwnerIdentity;
+	/** Who may talk to the agents, and at which tier. */
+	speakers: SpeakerPolicy;
+	team: Pick<
+		AgentTeam,
+		| "guildId"
+		| "owns"
+		| "answerOwner"
+		| "answerGroup"
+		| "answerBackground"
+		| "startFresh"
+	>;
+	runtime: Pick<AgentRuntime, "steer">;
+	surface: Pick<ChatSurface, "react" | "unreact">;
+	/** Where a channel's attachments are saved. */
+	attachmentDir: (channel: ChannelKey) => string;
+	logger: Logger;
+	/** Replaceable in tests. */
+	fetchImpl?: typeof fetch;
+}
+
+/**
+ * The agent server's channels: every owner message in an agent's or group's channel is answered
+ * there, mention or not, and an outside webhook's post in an agent's channel, such as a CI
+ * failure notice, is a labelled report turn for the agent.
+ */
+export function agentClaim(options: AgentClaimOptions): ChannelClaim {
+	const { speakers, team, runtime, surface, attachmentDir, logger, fetchImpl } =
+		options;
+	const attachments = (message: InboundMessage) =>
+		attachmentsOf(message, attachmentDir(message.channel), logger, fetchImpl);
+
+	const webhookReport = (message: InboundMessage): Admission | undefined => {
+		const text = message.text.trim();
+		if (!text) return undefined;
+		return {
+			kind: "background",
+			turn: {
+				channel: message.channel,
+				mode: "owner",
+				author: { id: message.authorId, name: message.authorName },
+				turnId: `webhook-${message.messageId}`,
+				text: `Webhook "${message.authorName}" posted in your channel:\n${text}`,
+				report: true,
+			},
+			unanswered: (result) =>
+				logger.warn(
+					{
+						channel: message.channel,
+						webhook: message.webhookId,
+						outcome: result,
+					},
+					"webhook post not answered",
+				),
+		};
+	};
+
+	return {
+		name: "agent-server",
+		priority: AGENT_SERVER_PRIORITY,
+		owns: (channel, guildId) =>
+			team.owns(channel) !== undefined ||
+			(guildId !== undefined && guildId === team.guildId),
+		admit: (message) => {
+			const owned = team.owns(message.channel);
+			// The agent server's other channels are the owner's notes: nothing there is answered.
+			if (!owned) return undefined;
+			if (owned === "agent" && message.webhookId && !message.ownWebhook)
+				return webhookReport(message);
+			if (message.authorIsBot) return undefined;
+			const speaker = speakers.resolve({
+				id: message.authorId,
+				name: message.authorName,
+				...(message.authorRoleIds ? { roleIds: message.authorRoleIds } : {}),
+			});
+			if (!speaker) return undefined;
+			const { channel, messageId } = message;
+			const forwarder = addressee(speaker, options.owner);
+			return {
+				kind: "turn",
+				busy: {
+					// A group's round is not steered; its messages wait their turn.
+					...(owned === "agent"
+						? {
+								steer: async () =>
+									runtime.steer(
+										channel,
+										attributed(speaker, withReference(message, forwarder)),
+										await attachments(message),
+										speaker.id,
+									),
+							}
+						: {}),
+					react: (emoji) => surface.react(channel, messageId, emoji),
+					unreact: (emoji) => surface.unreact(channel, messageId, emoji),
+				},
+				run: async () => {
+					const saved = await attachments(message);
+					const text = withReference(message, forwarder);
+					// A group's history already names each author.
+					if (owned === "agent")
+						await team.answerOwner(
+							channel,
+							speaker,
+							attributed(speaker, text),
+							message.text,
+							saved,
+						);
+					else
+						await team.answerGroup(
+							channel,
+							speaker,
+							text,
+							message.text,
+							saved,
+							message.reference?.webhookName,
+						);
+				},
+				failure: "agent message handling failed",
+			};
+		},
+		background: async (turn) => {
+			if (turn.mode === "party")
+				return { status: "skipped", reason: "party mode is off" };
+			const owned = team.owns(turn.channel);
+			if (owned === "group")
+				return { status: "skipped", reason: "groups have no schedules" };
+			return outcome(
+				await team.answerBackground(
+					turn.channel,
+					{
+						id: turn.author.id,
+						name: turn.author.name,
+						tier: turn.tier ?? "owner",
+					},
+					turn.text,
+					turn.report === true,
+				),
+			);
+		},
+		startFresh: async (channel) => {
+			await team.startFresh(channel);
+			return "agent";
+		},
+	};
+}

package/src/core/agents/agent-dashboard.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import { silentLogger } from "../log.ts";
+import { AgentDashboard, dashboardSections } from "./agent-dashboard.ts";
+import type { TeamStatus } from "./agent-team.ts";
+
+const NOW = new Date("2026-09-27T06:30:00Z");
+const TRACES = "https://example.com/traces/";
+const APP = "https://example.com/app/";
+/** The plugins' lines: the web app's, then the trace viewer's. */
+const LINES = [
+	`🧭 [Web app](${APP}) full dashboard, notes, and cleanup`,
+	`🔭 [Traces](${TRACES}) each message's model, tools, and tokens`,
+];
+
+const status: TeamStatus = {
+	agents: [
+		{
+			name: "infra",
+			displayName: "Infra",
+			channelId: "11",
+			model: "openai-codex/gpt-6-sol",
+			thinking: "high",
+			workingIn: "12",
+			waiting: 2,
+			context: { tokens: 42_000, contextWindow: 200_000 },
+			lastActive: new Date("2026-09-27T06:03:00Z"),
+			schedules: 1,
+		},
+		{
+			name: "doctor",
+			displayName: "Bot Doctor",
+			channelId: "13",
+			model: "claude-bridge/claude-opus-5-5",
+			thinking: "medium",
+			waiting: 0,
+			schedules: 0,
+		},
+	],
+	groups: [
+		{
+			name: "ops",
+			displayName: "Ops group",
+			channelId: "12",
+			members: ["Coordinator", "Infra"],
+			host: "Coordinator",
+			busy: 1,
+			lastActive: new Date("2026-09-26T06:03:00Z"),
+		},
+	],
+};
+
+describe("dashboardSections", () => {
+	test("shows the plugins' links, then each agent's and group's state", () => {
+		const [header, agents, groups] = dashboardSections(status, LINES, NOW);
+		// The header the links were written into before plugins contributed them, byte for byte.
+		expect(header).toBe(
+			"## Agent server\n🧭 [Web app](https://example.com/app/) full dashboard, notes, and cleanup\n🔭 [Traces](https://example.com/traces/) each message's model, tools, and tokens\n-# Updated 06:30; refreshed when a turn starts or ends, at most every 10 seconds",
+		);
+		expect(agents).toContain("**Infra** <#11>");
+		expect(agents).toContain("`openai-codex/gpt-6-sol` · thinking `high`");
+		expect(agents).toContain(
+			"🟠 Working (<#12>), 2 queued · context 42k / 200k (21%)",
+		);
+		expect(agents).toContain("-# Schedules 1 · Last active 06:03");
+		expect(agents).toContain("🟢 Idle · context —");
+		expect(agents).toContain("No activity since startup");
+		expect(groups).toContain("**Ops group** <#12>");
+		expect(groups).toContain("Members: Coordinator, Infra | Host: Coordinator");
+		expect(groups).toContain("🟠 1 in progress");
+		expect(groups).toContain("-# Last active 09-26 06:03");
+	});
+
+	test("stays within Discord's text limit, saying how many were left out", () => {
+		const many: TeamStatus = {
+			agents: Array.from({ length: 60 }, (_, i) => ({
+				...status.agents[1],
+				name: `a${i}`,
+				displayName: `Agent ${i}`,
+			})) as TeamStatus["agents"],
+			groups: [],
+		};
+		const sections = dashboardSections(many, LINES, NOW);
+		expect(sections.join("").length).toBeLessThan(4000);
+		expect(sections[1]).toMatch(/\d+ more not listed/);
+		expect(sections[2]).toContain("None.");
+	});
+});
+
+describe("AgentDashboard", () => {
+	test("updates at once, then at most once per interval, and keeps going after a failure", async () => {
+		const shown: string[][] = [];
+		let fail = true;
+		const dashboard = new AgentDashboard({
+			status: async () => status,
+			board: {
+				show: async (sections) => {
+					if (fail) {
+						fail = false;
+						throw new Error("discord down");
+					}
+					shown.push(sections);
+				},
+			},
+			lines: () => LINES,
+			logger: silentLogger(),
+			minIntervalMs: 40,
+			refreshMs: 60_000,
+		});
+		dashboard.start();
+		await Bun.sleep(10);
+		expect(shown).toHaveLength(0);
+		dashboard.changed();
+		dashboard.changed();
+		await Bun.sleep(15);
+		expect(shown).toHaveLength(0);
+		await Bun.sleep(50);
+		expect(shown).toHaveLength(1);
+		dashboard.stop();
+	});
+});

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

@@ -0,0 +1,185 @@
+import { messages } from "../i18n/index.ts";
+import type { Logger } from "../log.ts";
+import { thinkingLabel } from "../models.ts";
+import { zonedDate, zonedStamp } from "../time.ts";
+import type { ContextUse, DashboardBoard } from "./agent-ports.ts";
+import type { AgentStatus, GroupStatus, TeamStatus } from "./agent-team.ts";
+
+/** At most one edit this often (spec behavior 50); Discord limits message edits per channel. */
+const DASHBOARD_MIN_INTERVAL_MS = 10_000;
+/** Refreshed this often regardless, so last-activity times and context use stay current. */
+const DASHBOARD_REFRESH_MS = 5 * 60_000;
+/** Components V2 allows 4000 characters of text per message. */
+const TEXT_BUDGET = 3_800;
+
+/** Configured local time, with the month and day when it is not today's. */
+function when(at: Date, now: Date): string {
+	const date = zonedDate(at);
+	const clock = zonedStamp(at).slice(11);
+	return date === zonedDate(now) ? clock : `${date.slice(5)} ${clock}`;
+}
+
+const kilo = (tokens: number) => `${Math.round(tokens / 1000)}k`;
+
+function contextText(context: ContextUse | undefined): string {
+	const text = messages();
+	if (!context) return text.dashContextNone;
+	if (context.tokens === null)
+		return text.dashContextCompacted(kilo(context.contextWindow));
+	const percent = Math.round((context.tokens / context.contextWindow) * 100);
+	return text.dashContext(
+		kilo(context.tokens),
+		kilo(context.contextWindow),
+		percent,
+	);
+}
+
+function agentState(agent: AgentStatus): string {
+	const text = messages();
+	if (agent.workingIn) return text.dashWorking(agent.workingIn, agent.waiting);
+	return agent.waiting > 0 ? text.dashQueued(agent.waiting) : text.dashIdle;
+}
+
+function agentBlock(agent: AgentStatus, now: Date): string {
+	const channel = agent.channelId ? ` <#${agent.channelId}>` : "";
+	const text = messages();
+	const last = agent.lastActive
+		? text.dashLastActive(when(agent.lastActive, now))
+		: text.dashNotActive;
+	return [
+		`**${agent.displayName}**${channel}`,
+		`\`${agent.model}\` · thinking \`${thinkingLabel(agent.thinking)}\``,
+		`${agentState(agent)} · ${contextText(agent.context)}`,
+		text.dashAgentFooter(agent.schedules, last),
+	].join("\n");
+}
+
+function groupBlock(group: GroupStatus, now: Date): string {
+	const text = messages();
+	const state = group.busy > 0 ? text.dashGroupBusy(group.busy) : text.dashIdle;
+	const last = group.lastActive
+		? text.dashLastActive(when(group.lastActive, now))
+		: text.dashNotActive;
+	return [
+		`**${group.displayName}** <#${group.channelId}>`,
+		text.dashGroupMembers(group.members, group.host),
+		state,
+		`-# ${last}`,
+	].join("\n");
+}
+
+/** Joins blocks under a heading until the text budget runs out, then says how many were left. */
+function listed(heading: string, blocks: string[], budget: number): string {
+	let text = heading;
+	for (const [index, block] of blocks.entries()) {
+		if (text.length + block.length + 2 > budget) {
+			return `${text}\n\n${messages().dashMore(blocks.length - index)}`;
+		}
+		text += `\n\n${block}`;
+	}
+	return blocks.length > 0 ? text : `${text}\n${messages().dashNone}`;
+}
+
+/**
+ * The dashboard message: the plugins' lines, such as links, then every active agent and group
+ * (spec behavior 49; web app spec behavior 6).
+ */
+export function dashboardSections(
+	status: TeamStatus,
+	lines: readonly string[],
+	now: Date,
+): string[] {
+	const text = messages();
+	const header = [
+		text.dashTitle,
+		...lines,
+		text.dashUpdated(when(now, now)),
+	].join("\n");
+	const budget = (TEXT_BUDGET - header.length) / 2;
+	return [
+		header,
+		listed(
+			"### Agents",
+			status.agents.map((agent) => agentBlock(agent, now)),
+			budget,
+		),
+		listed(
+			text.dashGroupsHeading,
+			status.groups.map((group) => groupBlock(group, now)),
+			budget,
+		),
+	];
+}
+
+export interface AgentDashboardOptions {
+	status: () => Promise<TeamStatus>;
+	board: DashboardBoard;
+	/** The plugins' lines under the title, read at each update. */
+	lines: () => readonly string[];
+	logger: Logger;
+	minIntervalMs?: number;
+	refreshMs?: number;
+}
+
+/**
+ * Keeps the dashboard message current: an update right after `changed()` unless one ran in the
+ * last interval, in which case one runs when the interval ends; plus a periodic refresh.
+ */
+export class AgentDashboard {
+	readonly #options: AgentDashboardOptions;
+	#lastRun = 0;
+	#pending: ReturnType<typeof setTimeout> | undefined;
+	#refresh: ReturnType<typeof setInterval> | undefined;
+	#running: Promise<void> | undefined;
+
+	constructor(options: AgentDashboardOptions) {
+		this.#options = options;
+	}
+
+	start(): void {
+		this.changed();
+		this.#refresh = setInterval(
+			() => this.changed(),
+			this.#options.refreshMs ?? DASHBOARD_REFRESH_MS,
+		);
+	}
+
+	stop(): void {
+		clearTimeout(this.#pending);
+		clearInterval(this.#refresh);
+		this.#pending = undefined;
+	}
+
+	changed(): void {
+		if (this.#pending) return;
+		const interval = this.#options.minIntervalMs ?? DASHBOARD_MIN_INTERVAL_MS;
+		const wait = Math.max(0, this.#lastRun + interval - Date.now());
+		this.#pending = setTimeout(() => {
+			this.#pending = undefined;
+			void this.#update();
+		}, wait);
+	}
+
+	/** One update at a time; a change during an update schedules the next one. */
+	async #update(): Promise<void> {
+		if (this.#running) {
+			await this.#running;
+			this.changed();
+			return;
+		}
+		this.#lastRun = Date.now();
+		this.#running = this.#show().finally(() => {
+			this.#running = undefined;
+		});
+		await this.#running;
+	}
+
+	async #show(): Promise<void> {
+		const { status, board, lines, logger } = this.#options;
+		try {
+			await board.show(dashboardSections(await status(), lines(), new Date()));
+		} catch (error) {
+			logger.warn({ err: error }, "dashboard not updated");
+		}
+	}
+}