pi-roundtable 0.1.0

package/src/core/agents/team-status.ts

@@ -0,0 +1,80 @@
+import type { ThinkingSetting } from "../models.ts";
+import type { ContextUse } from "./agent-ports.ts";
+import { channelIdOf, channelKey } from "./team-keys.ts";
+import type { TeamContext } from "./team-options.ts";
+
+/** An active agent as the dashboard shows it. */
+export interface AgentStatus {
+	name: string;
+	displayName: string;
+	channelId?: string;
+	model: string;
+	thinking: ThinkingSetting;
+	/** The channel of its running turn: its own, a group's, or where it answers a message. */
+	workingIn?: string;
+	/** Turns waiting in its own channel. */
+	waiting: number;
+	context?: ContextUse;
+	lastActive?: Date;
+	schedules: number;
+}
+
+/** An active group as the dashboard shows it. */
+export interface GroupStatus {
+	name: string;
+	displayName: string;
+	channelId: string;
+	members: string[];
+	host: string;
+	/** Messages of its channel running or waiting, a round counting as one. */
+	busy: number;
+	lastActive?: Date;
+}
+
+export interface TeamStatus {
+	agents: AgentStatus[];
+	groups: GroupStatus[];
+}
+
+/** Every active agent and group, with what each is doing now. */
+export async function teamStatus(ctx: TeamContext): Promise<TeamStatus> {
+	const { options, turns } = ctx;
+	const { store, queue, schedules } = options;
+	const runtime = options.runtime();
+	const agents: AgentStatus[] = [];
+	for (const agent of store.agents()) {
+		if (agent.status !== "active") continue;
+		const home = agent.channelId ? channelKey(agent.channelId) : undefined;
+		const workingIn = turns.workingIn(agent.name);
+		const queued = home ? queue.size(home) : 0;
+		const context = home ? runtime.contextUsage(home) : undefined;
+		const lastActive = turns.lastActive(agent.name);
+		agents.push({
+			name: agent.name,
+			displayName: agent.displayName,
+			...(agent.channelId ? { channelId: agent.channelId } : {}),
+			...ctx.modelOf(agent.name),
+			...(workingIn ? { workingIn: channelIdOf(workingIn) } : {}),
+			waiting: Math.max(0, queued - (workingIn === home ? 1 : 0)),
+			...(context ? { context } : {}),
+			...(lastActive ? { lastActive } : {}),
+			schedules: home ? (await schedules.forChannel(home)).length : 0,
+		});
+	}
+	const groups: GroupStatus[] = store
+		.groups()
+		.filter((group) => group.status === "active")
+		.map((group) => {
+			const lastActive = turns.lastGroupActive(group.name);
+			return {
+				name: group.name,
+				displayName: group.displayName,
+				channelId: group.channelId,
+				members: group.members.map((m) => store.agent(m)?.displayName ?? m),
+				host: store.agent(group.host)?.displayName ?? group.host,
+				busy: queue.size(channelKey(group.channelId)),
+				...(lastActive ? { lastActive } : {}),
+			};
+		});
+	return { agents, groups };
+}

package/src/core/agents/team-text.ts

@@ -0,0 +1,60 @@
+import { AgentError } from "../domain/errors.ts";
+import { assistantName } from "../i18n/index.ts";
+import type { ThinkingSetting } from "../models.ts";
+import { zonedStamp } from "../time.ts";
+import type { ChannelMessage } from "./agent-ports.ts";
+import { describeThinking } from "./agent-settings.ts";
+import type { Agent, AgentStore } from "./agent-store.ts";
+
+/** One message as channel_read shows it: id, local time, author, text, attachments. */
+export function messageLine(message: ChannelMessage): string {
+	const files =
+		message.attachments.length > 0
+			? ` [attachments: ${message.attachments.join(", ")}]`
+			: "";
+	return `[${message.id}] ${zonedStamp(message.at)} ${message.author}: ${message.text}${files}`;
+}
+
+/** A channel given as `<#id>` or its id, as its id. */
+export function channelIdFromRef(channel: string): string {
+	const id = /^<#(\d+)>$/.exec(channel.trim())?.[1] ?? channel.trim();
+	if (!/^\d+$/.test(id))
+		throw new AgentError(
+			"Give the channel as <#id> or its id, as in a forwarded message.",
+		);
+	return id;
+}
+
+/** Every agent and group as agent_list shows them, before the category layout. */
+export function teamListText(store: Pick<AgentStore, "agents" | "groups">) {
+	const agents = store.agents().map((a) => {
+		const channel = a.channelId ? `<#${a.channelId}>` : "no channel";
+		return `- ${a.name} "${a.displayName}" — ${channel}, ${a.status}`;
+	});
+	const groups = store
+		.groups()
+		.map(
+			(g) =>
+				`- ${g.name} "${g.displayName}" — <#${g.channelId}>, ${g.status}; members ${g.members.join(", ")}; host ${g.host}`,
+		);
+	return `Agents:\n${agents.join("\n") || "none"}\n\nGroups:\n${groups.join("\n") || "none"}`;
+}
+
+/** One agent as agent_get shows it; unset settings name the assistant's. */
+export function agentDetails(
+	agent: Agent,
+	defaults: { model: string; thinking: ThinkingSetting },
+	skills: string,
+): string {
+	return [
+		`Name: ${agent.name}`,
+		`Display name: ${agent.displayName}`,
+		`Status: ${agent.status}`,
+		`Channel: ${agent.channelId ? `<#${agent.channelId}>` : "none"}`,
+		`Model: ${agent.model ?? `${assistantName()}'s (${defaults.model})`}`,
+		`Thinking: ${agent.thinking ?? `${assistantName()}'s (${describeThinking(defaults.thinking)})`}`,
+		`Skills: ${skills}`,
+		`Avatar prompt: ${agent.avatarPrompt}`,
+		`Prompt:\n${agent.prompt}`,
+	].join("\n");
+}

package/src/core/agents/team-turn-types.ts

@@ -0,0 +1,107 @@
+import type { QueuePort } from "../contract/channels.ts";
+import type {
+	DispatchThread,
+	DispatchThreads,
+} from "../discord/dispatch-threads.ts";
+import type { TurnAttachments } from "../domain/attachment.ts";
+import type {
+	ChannelKey,
+	PendingConfirmation,
+	TurnResult,
+} from "../domain/conversation.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import type { Logger } from "../log.ts";
+import type { EventSink } from "../plugin.ts";
+import type { TurnSelection } from "../sessions.ts";
+import type { Speaker } from "../speakers.ts";
+import type { ToolTiers } from "../tool-tiers.ts";
+import type { AgentChannels, AgentTurnRunner } from "./agent-ports.ts";
+import type { Agent, AgentStore } from "./agent-store.ts";
+import type { AvatarStudio } from "./avatar-studio.ts";
+import type { RelevanceScorer } from "./group-round.ts";
+
+/** Agent messages without an owner message in between (spec behavior 13). */
+export const MAX_CHAIN_MESSAGES = 8;
+export const BACKLOG_LIMIT = 40;
+
+/** A run of agent messages started by one owner message, schedule, or report. */
+export interface Chain {
+	messages: number;
+	/** Whoever started the run; the agents it wakes work for the same person. */
+	speaker: Speaker;
+}
+
+/** A message's thread in the sender's turn channel, which holds the request and the answer. */
+export interface Exchange {
+	parent: ChannelKey;
+	thread: DispatchThread;
+}
+
+export interface TeamTurnsOptions {
+	/** The agent server's entry channel, where the coordinator lives. */
+	entryChannelId: string;
+	/** Who the agents work for, as their prompts and group history name them. */
+	owner: OwnerIdentity;
+	store: AgentStore;
+	channels: Pick<AgentChannels, "post">;
+	studio: Pick<AvatarStudio, "url">;
+	/** Set once the runtime exists, which itself needs the team's tools. */
+	runtime: () => AgentTurnRunner;
+	/** The tools every agent turn runs with. */
+	selection: (scope: AgentTurnScope) => TurnSelection;
+	/** The lowest tier that may use each tool, which also decides who may approve a held one. */
+	toolTiers?: ToolTiers;
+	/** Judges whether an owner message approves held actions. */
+	confirmations: {
+		approves(pending: PendingConfirmation, reply: string): Promise<boolean>;
+	};
+	scorer: Pick<RelevanceScorer, "score">;
+	/** Shared with the conversation service, so each channel runs one turn at a time. */
+	queue: QueuePort;
+	startTyping(channel: ChannelKey): () => void;
+	/** The owner's stop button for a turn in an agent's own channel, until the returned function is called. */
+	showStop(channel: ChannelKey): () => void;
+	logger: Logger;
+	/** Called when a turn starts or ends. */
+	changed(): void;
+	/** Where turns and team changes are reported for the plugins' handlers. */
+	events?: EventSink;
+	/** A thread for each message between agents; without it both go in the sender's channel. */
+	threads?: Pick<DispatchThreads, "open">;
+}
+
+/** How a turn runs, beyond its text. */
+export interface TurnExtra {
+	attachments?: TurnAttachments;
+	confirmed?: boolean;
+	steerable?: boolean;
+	/** The owner started it by writing, or it delivers a report, so it may ask him on cards. */
+	interactive?: boolean;
+}
+
+/** What the team's message and group collaborators need of the turns that own their state. */
+export interface TurnHost {
+	readonly options: TeamTurnsOptions;
+	/** The chain of each running turn, by session key. */
+	readonly chains: ReadonlyMap<ChannelKey, Chain>;
+	/** Runs one agent turn and posts its reply under the agent's name; never rejects. */
+	turn(
+		agent: Agent,
+		scope: AgentTurnScope,
+		postTo: ChannelKey,
+		text: string,
+		chain: Chain,
+		extra?: TurnExtra,
+	): Promise<TurnResult>;
+	post(
+		channel: ChannelKey,
+		as: Agent,
+		body: { thinking?: string; chunks: string[]; threadId?: string },
+	): Promise<void>;
+	/** The agent's latest row. */
+	current(agent: Agent): Agent;
+	/** Whether the speaker's tier holds every tool of the held actions. */
+	mayApprove(speaker: Speaker, pending: PendingConfirmation): boolean;
+	turnChannel(scope: AgentTurnScope): ChannelKey;
+}

package/src/core/agents/team-turns.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, test } from "bun:test";
+import { NO_ATTACHMENTS } from "../domain/attachment.ts";
+import type {
+	PendingConfirmation,
+	TurnResult,
+} from "../domain/conversation.ts";
+import { AgentRunError } from "../domain/errors.ts";
+import type { AgentTurnScope, TurnRequest } from "../domain/ports.ts";
+import { messages } from "../i18n/index.ts";
+import { silentLogger } from "../log.ts";
+import { ChannelQueue } from "../routing/channel-queue.ts";
+import { TEST_OWNER as OWNER, OWNER_SPEAKER } from "../testing/owner.ts";
+import { FakeThreadHost, fakeThreads } from "../testing/thread-host.ts";
+import type { AgentPost } from "./agent-ports.ts";
+import type { Agent, AgentGroup, AgentStore } from "./agent-store.ts";
+import { channelKey } from "./team-keys.ts";
+import { TeamTurns } from "./team-turns.ts";
+
+const agent = (name: string, channelId: string): Agent => ({
+	name,
+	displayName: name === "infra" ? "Infrastructure" : "Coordinator",
+	prompt: "",
+	avatarPrompt: "",
+	channelId,
+	status: "active",
+});
+
+const AGENTS = [agent("coordinator", "1000"), agent("infra", "2000")];
+const GROUP: AgentGroup = {
+	name: "ops",
+	displayName: "Ops",
+	channelId: "3000",
+	members: ["coordinator", "infra"],
+	host: "coordinator",
+	status: "active",
+};
+
+/** The store methods messages between agents read, over two agents and one group. */
+const store = {
+	agent: (name: string) => AGENTS.find((a) => a.name === name),
+	activeAgent: (name: string) => {
+		const found = AGENTS.find((a) => a.name === name);
+		if (!found) throw new Error(`no agent ${name}`);
+		return found;
+	},
+	agentByChannel: (id: string) => AGENTS.find((a) => a.channelId === id),
+	group: (name: string) => (name === GROUP.name ? GROUP : undefined),
+	groupByChannel: (id: string) => (id === GROUP.channelId ? GROUP : undefined),
+} as unknown as AgentStore;
+
+const coordinator: AgentTurnScope = {
+	name: "coordinator",
+	session: channelKey("1000"),
+	home: channelKey("1000"),
+};
+
+function setup(
+	answer: (request: TurnRequest) => TurnResult,
+	host = new FakeThreadHost(),
+	withThreads = true,
+	held?: PendingConfirmation,
+) {
+	const posts: { channelId: string; post: AgentPost }[] = [];
+	const turns: TurnRequest[] = [];
+	/** The replies the judge was asked to read as approvals. */
+	const judged: string[] = [];
+	const { threads } = fakeThreads(host);
+	const queue = new ChannelQueue();
+	const team = new TeamTurns({
+		owner: OWNER,
+		entryChannelId: "1000",
+		store,
+		channels: {
+			post: async (channelId, post) => {
+				posts.push({ channelId, post });
+			},
+		},
+		studio: { url: () => "https://x/a.png" },
+		runtime: () => ({
+			runTurn: async (request) => {
+				turns.push(request);
+				return answer(request);
+			},
+			heldActions: async () => held,
+			startFresh: async () => undefined,
+			contextUsage: () => undefined,
+		}),
+		selection: () => ({ id: "agent", tools: [], groups: [] }),
+		confirmations: {
+			approves: async (_pending, reply) => {
+				judged.push(reply);
+				return true;
+			},
+		},
+		scorer: { score: async () => undefined },
+		queue,
+		startTyping: () => () => undefined,
+		showStop: () => () => undefined,
+		logger: silentLogger(),
+		changed: () => undefined,
+		...(withThreads ? { threads } : {}),
+	});
+	/** Posts in a channel, or in one of its threads, as `name: text`. */
+	const texts = (channelId: string, threadId?: string) =>
+		posts
+			.filter((p) => p.channelId === channelId && p.post.threadId === threadId)
+			.map((p) => `${p.post.name}: ${p.post.chunks.join("")}`);
+	return { team, host, posts, turns, texts, judged };
+}
+
+/** Runs a coordinator turn, whose model sends the message, and waits for the chain to settle. */
+async function run(team: TeamTurns): Promise<void> {
+	await team.answerBackground(channelKey("1000"), OWNER_SPEAKER, "go");
+	for (let i = 0; i < 30; i++) await Bun.sleep(2);
+}
+
+describe("message_agent threads", () => {
+	test("the exchange goes in a thread of the sender's channel, archived before the sender's follow-up", async () => {
+		let archivedAtFollowUp: string[] | undefined;
+		const host = new FakeThreadHost();
+		const { team, texts, turns } = setup((request) => {
+			if (request.agent?.name === "coordinator" && turns.length === 1)
+				team.message(coordinator, "infra", "check the disk");
+			if (request.agent?.name === "coordinator" && turns.length > 1)
+				archivedAtFollowUp = [...host.closed];
+			return {
+				ok: true,
+				text: request.agent?.name === "infra" ? "disk 80%" : "ok",
+			};
+		}, host);
+		await run(team);
+		expect(host.opened).toEqual([
+			{ parentId: "1000", name: "→ Infrastructure", id: "900" },
+		]);
+		expect(host.lines.get("1000")).toBe(
+			messages().threadStarted("→ Infrastructure", "<#900>"),
+		);
+		expect(texts("1000", "900")).toEqual([
+			`Coordinator: ${messages().messageDelivered("Infrastructure", "check the disk")}`,
+			`Infrastructure: ${messages().answerReturned("disk 80%")}`,
+		]);
+		// The target's own channel is unchanged; the sender's channel holds only its own replies.
+		expect(texts("2000")).toEqual([
+			`Coordinator: ${messages().messageDelivered("Infrastructure", "check the disk")}`,
+			"Infrastructure: disk 80%",
+		]);
+		expect(texts("1000")).toEqual(["Coordinator: ok", "Coordinator: ok"]);
+		expect(archivedAtFollowUp).toEqual(["900"]);
+		const followUp = turns.at(-1);
+		expect(followUp?.channel).toBe(channelKey("1000"));
+		expect(followUp?.text).toContain("in the thread <#900>");
+		expect(followUp?.text).toContain("disk 80%"); // Only the answer's follow-up is a report turn, which may ask the owner on cards.
+		expect(turns.map((t) => [t.agent?.name, t.interactive])).toEqual([
+			["coordinator", undefined],
+			["infra", undefined],
+			["coordinator", true],
+		]);
+	});
+
+	test("a report turn in an agent's channel may ask on cards; a schedule's may not", async () => {
+		const { team, turns } = setup(() => ({ ok: true, text: "ok" }));
+		await team.answerBackground(channelKey("1000"), OWNER_SPEAKER, "scheduled");
+		await team.answerBackground(
+			channelKey("1000"),
+			OWNER_SPEAKER,
+			"report",
+			true,
+		);
+		expect(turns.map((t) => t.interactive)).toEqual([undefined, true]);
+	});
+
+	test("a failed or stopped answer is reported in the thread, which is archived", async () => {
+		const { team, host, turns } = setup((request) => {
+			if (request.agent?.name === "coordinator" && turns.length === 1)
+				team.message(coordinator, "infra", "x");
+			return request.agent?.name === "infra"
+				? {
+						ok: false,
+						error: new AgentRunError("stopped by the owner"),
+						stopped: true,
+					}
+				: { ok: true, text: "ok" };
+		});
+		await run(team);
+		expect(host.textsIn("900")).toEqual([
+			messages().agentNoReply("stopped by the owner"),
+		]);
+		expect(host.closed).toEqual(["900"]);
+		expect(turns.at(-1)?.text).toContain("could not answer");
+		expect(turns.at(-1)?.text).toContain("<#900>");
+	});
+
+	test("without a thread the answer comes back in the sender's channel as before", async () => {
+		const host = new FakeThreadHost();
+		host.failOpen = true;
+		const { team, texts, turns } = setup((request) => {
+			if (request.agent?.name === "coordinator" && turns.length === 1)
+				team.message(coordinator, "infra", "x");
+			return { ok: true, text: `${request.agent?.name} ok` };
+		}, host);
+		await run(team);
+		expect(texts("1000")).toContain(
+			`Infrastructure: ${messages().answerReturned("infra ok")}`,
+		);
+		expect(turns.at(-1)?.text).not.toContain("thread");
+	});
+
+	test("a group round's dispatches open their threads in the group channel", () => {
+		const { team } = setup(() => ({ ok: true, text: "" }), undefined, false);
+		expect(team.turnChannel({ ...coordinator, group: "ops" })).toBe(
+			channelKey("3000"),
+		);
+		expect(team.turnChannel(coordinator)).toBe(channelKey("1000"));
+	});
+});
+
+describe("speakers", () => {
+	test("a message chain keeps the speaker who started it through every hop", async () => {
+		const admin = { id: "2", name: "Ada", tier: "admin" } as const;
+		const { team, turns } = setup((request) => {
+			if (request.agent?.name === "coordinator" && turns.length === 1)
+				team.message(coordinator, "infra", "check the disk");
+			return { ok: true, text: "ok" };
+		});
+		await team.answerBackground(channelKey("1000"), admin, "go");
+		for (let i = 0; i < 30; i++) await Bun.sleep(2);
+		expect(turns.map((t) => [t.agent?.name, t.speaker])).toEqual([
+			["coordinator", admin],
+			["infra", admin],
+			["coordinator", admin],
+		]);
+	});
+});
+
+describe("approvals", () => {
+	const shell: PendingConfirmation = {
+		profile: "general",
+		heldAt: new Date(),
+		calls: [{ tool: "bash", input: "{}", action: "run a command" }],
+	};
+	const answer = () => ({ ok: true, text: "ok" }) as const;
+	const reply = (
+		team: TeamTurns,
+		tier: "owner" | "admin" | "member",
+	): Promise<unknown> =>
+		team.answerOwner(
+			channelKey("1000"),
+			{ id: "2", name: "Ada", tier },
+			"yes, run it",
+			"yes, run it",
+			NO_ATTACHMENTS,
+		);
+
+	test("a speaker whose tier holds the held tool approves it", async () => {
+		const { team, turns, judged } = setup(answer, undefined, true, shell);
+		await reply(team, "owner");
+		expect(judged).toEqual(["yes, run it"]);
+		expect(turns[0]?.confirmed).toBe(true);
+	});
+
+	test("a lower tier is not asked to approve, so the held action stays held", async () => {
+		const { team, turns, judged } = setup(answer, undefined, true, shell);
+		await reply(team, "admin");
+		await reply(team, "member");
+		expect(judged).toEqual([]);
+		expect(turns.map((t) => t.confirmed)).toEqual([undefined, undefined]);
+	});
+
+	test("an admin approves what an admin may use", async () => {
+		const held: PendingConfirmation = {
+			...shell,
+			calls: [{ tool: "agent_create", input: "{}", action: "create an agent" }],
+		};
+		const { team, turns } = setup(answer, undefined, true, held);
+		await reply(team, "admin");
+		expect(turns[0]?.confirmed).toBe(true);
+	});
+});