pi-roundtable 0.1.0

package/src/core/attachments/turn-attachments.ts

@@ -0,0 +1,79 @@
+import type { TurnAttachments } from "../domain/attachment.ts";
+import type { InboundMessage } from "../domain/conversation.ts";
+import type { Logger } from "../log.ts";
+import { fetchAttachments } from "./attachment-fetcher.ts";
+import {
+	isModelImage,
+	MAX_IMAGES_PER_TURN,
+	prepareImage,
+} from "./image-prep.ts";
+
+/** Saves the message's and its reference's files, and turns up to four images into model images. */
+export async function collectAttachments(
+	message: InboundMessage,
+	dir: string,
+	options: { logger: Logger; fetchImpl?: typeof fetch },
+): Promise<TurnAttachments> {
+	const { fetchImpl, logger } = options;
+	const own = await fetchAttachments(
+		{
+			refs: message.attachments,
+			dir,
+			prefix: message.messageId,
+			fromReference: false,
+		},
+		fetchImpl,
+	);
+	const referenced = await fetchAttachments(
+		{
+			refs: message.reference?.attachments ?? [],
+			dir,
+			prefix: `${message.messageId}-ref`,
+			fromReference: true,
+		},
+		fetchImpl,
+	);
+	const files = [...own.files, ...referenced.files];
+	const failures = [...own.failures, ...referenced.failures];
+	const images = [];
+	for (const file of files.filter(isModelImage).slice(0, MAX_IMAGES_PER_TURN)) {
+		try {
+			images.push(await prepareImage(file));
+		} catch (error) {
+			logger.warn(
+				{ file: file.file, err: error },
+				"image could not be prepared",
+			);
+			failures.push({
+				name: file.name,
+				reason: "the image could not be decoded",
+				fromReference: file.fromReference,
+			});
+		}
+	}
+	if (files.length > 0 || failures.length > 0) {
+		logger.info(
+			{
+				channel: message.channel,
+				files: files.length,
+				images: images.length,
+				failures: failures.length,
+			},
+			"attachments received",
+		);
+	}
+	return { files, images, failures };
+}
+
+/** Collects a message's attachments into `dir`, reporting the files that failed. */
+export function attachmentsOf(
+	message: InboundMessage,
+	dir: string,
+	logger: Logger,
+	fetchImpl?: typeof fetch,
+): Promise<TurnAttachments> {
+	return collectAttachments(message, dir, {
+		logger,
+		...(fetchImpl ? { fetchImpl } : {}),
+	});
+}

package/src/core/boundary.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+const ROOT = resolve(import.meta.dir, "../..");
+const CORE = join(ROOT, "src/core");
+
+function coreFiles(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) return coreFiles(path);
+		return entry.name.endsWith(".ts") ? [path] : [];
+	});
+}
+
+/** Relative imports of a file, as repository paths. */
+function localImports(file: string): string[] {
+	const source = readFileSync(file, "utf8");
+	return [...source.matchAll(/from\s+"(\.{1,2}\/[^"]+)"/g)].map((match) =>
+		relative(ROOT, resolve(dirname(file), match[1] ?? "")),
+	);
+}
+
+describe("core boundary", () => {
+	test("the core imports only itself", () => {
+		const outside = coreFiles(CORE).flatMap((file) =>
+			localImports(file)
+				.filter((path) => !path.startsWith("src/core/"))
+				.map((path) => `${relative(ROOT, file)} -> ${path}`),
+		);
+		expect(outside).toEqual([]);
+	});
+
+	test("the core never imports a consumer's plugins", () => {
+		const consumers = readdirSync(join(ROOT, "src"), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && entry.name !== "core")
+			.map((entry) => `src/${entry.name}/`);
+		const found = coreFiles(CORE).flatMap((file) =>
+			localImports(file).filter((path) =>
+				consumers.some((prefix) => path.startsWith(prefix)),
+			),
+		);
+		expect(found).toEqual([]);
+	});
+});

package/src/core/builtin/agent-server.ts

@@ -0,0 +1,275 @@
+import type {
+	ExtensionFactory,
+	ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+import { agentClaim } from "../agents/agent-claim.ts";
+import { AgentDashboard } from "../agents/agent-dashboard.ts";
+import { AgentTeam } from "../agents/agent-team.ts";
+import { RelevanceScorer } from "../agents/group-round.ts";
+import { channelKey } from "../agents/team-keys.ts";
+import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
+import type { ChannelKey } from "../domain/conversation.ts";
+import type { OwnerIdentity } from "../identity.ts";
+import { ConfirmationJudge } from "../judging/confirmation-judge.ts";
+import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
+import {
+	AUTO_THINKING,
+	formatModelRef,
+	type ModelRef,
+	type ThinkingLevel,
+} from "../models.ts";
+import { SkillRegistry } from "../modules/skills/skill-registry.ts";
+import type { ErrorReporter } from "../ops/error-reporter.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { splitReply } from "../presentation/reply-splitter.ts";
+import { agentPromptExtension } from "../runtime/extensions/agent-prompt.ts";
+import { PiAgentRuntime } from "../runtime/pi-agent-runtime.ts";
+import type { AgentTurnScope, SessionTool } from "../sessions.ts";
+import type { SpeakerPolicy } from "../speakers.ts";
+
+export interface AgentServerOptions {
+	guildId: string;
+	/** The channel the coordinator lives in. */
+	entryChannelId: string;
+	owner: OwnerIdentity & { id: string };
+	/** The assistant's display name, as the confirmation judge names it. */
+	assistant: string;
+	/** Who may talk to the agents, and at which tier. */
+	speakers: SpeakerPolicy;
+	/** Shared with the rest of the host, so logins refresh in one place. */
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	dataDir: string;
+	/** The model of agents and of the assistant, and the thinking level a judge falls back to. */
+	model: ModelRef;
+	thinking: ThinkingLevel;
+	/** How sure the judges must be before their answer is used. */
+	judgeThreshold: number;
+	/** The shell's shared working directory. */
+	workDir: string;
+	/** The host account the agents' shell and file tools run as. */
+	shellUser: string;
+	/** The prompt every agent starts with, and the one for speakers other than the owner. */
+	prompts: { shared: string; guest?: string };
+	/** Where the skill registry reads and writes skills. */
+	skills: { reposDir: string; writtenDir: string; builtinDir: string };
+	/** The listener the avatar pictures are served on. */
+	avatarListener: string;
+	/** Reports the process's own errors to an agent; without one nothing is reported. */
+	errorReporter?: ErrorReporter;
+	/**
+	 * Conversations outside the agent server, such as the owner's own: their system prompt, and the
+	 * tools startup refuses to run without.
+	 */
+	ownerSessions?: { persona: string; requiredTools: readonly string[] };
+}
+
+/** A session tool whose extension never changes, for agent sessions only. */
+function agentOnly(
+	name: string,
+	factory: (scope: AgentTurnScope) => ExtensionFactory,
+): SessionTool {
+	return {
+		name,
+		phase: "tools",
+		snapshot: () => ({
+			revision: 0,
+			factory: (session) => (session.agent ? factory(session.agent) : null),
+		}),
+	};
+}
+
+/** The agent tools and the agent's own prompt, which only agent sessions load. */
+export function agentSessionTools(
+	team: Pick<AgentTeam, "extension" | "systemPrompt">,
+): SessionTool[] {
+	return [
+		agentOnly("agent-tools", (scope) => team.extension(scope)),
+		agentOnly("agent-prompt", (scope) =>
+			agentPromptExtension(() => team.systemPrompt(scope)),
+		),
+	];
+}
+
+/**
+ * The agent server: the skill registry, the team with its channels and dashboard, and the
+ * runtime that runs every agent turn. It claims the agent channels, starts the team in the
+ * background, and hands what it built to the plugins after it.
+ */
+export function agentServerPlugin(
+	options: AgentServerOptions,
+): RoundtablePlugin {
+	let runtime: PiAgentRuntime | undefined;
+	let team: AgentTeam | undefined;
+	let skills: SkillRegistry | undefined;
+	return {
+		name: "agent-server",
+		// The skills are read once every plugin is set up, so a plugin may still place some in setup.
+		preflight: async () => {
+			skills?.init();
+			await runtime?.preflight();
+		},
+		stopTurn: (channel) => runtime?.stop(channel) ?? false,
+		agentServer: () => team?.start() ?? Promise.resolve(),
+		setup: (context) => {
+			const { stores, discord } = context.core;
+			const { surface } = discord;
+			const { logger, providers } = context;
+			const judge = providers.judge;
+			const confirmations = new ConfirmationJudge({
+				judge,
+				threshold: options.judgeThreshold,
+				assistant: options.assistant,
+				logger,
+			});
+			const registry = new SkillRegistry({
+				store: stores.skills,
+				reposDir: options.skills.reposDir,
+				writtenDir: options.skills.writtenDir,
+				builtinDir: options.skills.builtinDir,
+				logger,
+			});
+			skills = registry;
+			const built: AgentTeam = new AgentTeam({
+				guildId: options.guildId,
+				entryChannelId: options.entryChannelId,
+				seeds: () => context.sessions().seeds,
+				promptSections: () => context.sessions().prompt,
+				pluginTools: () => context.sessions().agentTools,
+				pluginSelection: () => context.sessions().agentSelection(),
+				events: context.events,
+				owner: options.owner,
+				toolTiers: context.toolTiers,
+				shellUser: options.shellUser,
+				store: stores.agents,
+				channels: surface.agentChannels(options.guildId),
+				studio: discord.studio,
+				// The runtime is built next, with this team's tools.
+				runtime: () => {
+					if (!runtime) throw new Error("the runtime is built with the team");
+					return runtime;
+				},
+				confirmations,
+				scorer: new RelevanceScorer(judge, logger, options.owner),
+				models: {
+					defaults: {
+						model: formatModelRef(options.model),
+						thinking: AUTO_THINKING,
+					},
+					// The snapshot is filled in the background at startup; a form must open within 3 s.
+					usable: async () => {
+						const snapshot = options.modelRuntime.getAvailableSnapshot();
+						const models =
+							snapshot.length > 0
+								? snapshot
+								: await options.modelRuntime.getAvailable();
+						return models.map((model) => `${model.provider}/${model.id}`);
+					},
+				},
+				schedules: stores.schedules,
+				queue: context.queue,
+				startTyping: (channel) => surface.startTyping(channel),
+				showStop: (channel) => surface.showStop(channel),
+				workDir: options.workDir,
+				sharedPrompt: options.prompts.shared,
+				...(options.prompts.guest
+					? { guestPrompt: options.prompts.guest }
+					: {}),
+				skills: registry,
+				threads: discord.threads,
+				logger,
+			});
+			team = built;
+			surface.onChannelDeleted((channelId) => {
+				if (!built.owns(channelKey(channelId))) return;
+				void context.queue
+					.run(channelKey(channelId), () => built.channelDeleted(channelId))
+					// pi-lens-ignore: no-unknown-parameters
+					.catch((error: unknown) =>
+						logger.error({ channelId, err: error }, "archive failed"),
+					);
+			});
+			const running = new PiAgentRuntime({
+				owner: options.owner,
+				sessions: context.sessions,
+				agentDir: options.agentDir,
+				modelRuntime: options.modelRuntime,
+				dataDir: options.dataDir,
+				model: options.model,
+				thinking: options.thinking,
+				effort: new EffortJudge({
+					judge,
+					brief: AGENT_BRIEF,
+					fallback: options.thinking,
+					threshold: options.judgeThreshold,
+					logger,
+				}),
+				persona: options.ownerSessions?.persona ?? "",
+				confirmations: stores.confirmations,
+				requiredTools: options.ownerSessions?.requiredTools ?? [],
+				toolTiers: context.toolTiers,
+				agents: {
+					workDir: options.workDir,
+					modelOf: (name) => built.modelOf(name),
+					skills: (name) => built.skillsOf(name),
+					turnChannel: (scope) => built.turnChannel(scope),
+				},
+				prompts: (channel, speaker) => discord.cards.prompts(channel, speaker),
+				logger,
+			});
+			runtime = running;
+			context.core.provide("agents", {
+				team: built,
+				runtime: running,
+				skills: registry,
+				confirmations,
+			});
+			const attachmentDir = (channel: ChannelKey) =>
+				ownerAttachmentDir(options.dataDir, channel);
+			const dashboard = new AgentDashboard({
+				status: () => built.status(),
+				board: surface.agentDashboard(options.guildId),
+				lines: () => context.dashboard(),
+				logger,
+			});
+			built.onChange(() => dashboard.changed());
+			return {
+				services: [
+					{ name: "runtime", stop: () => running.dispose() },
+					{ name: "dashboard", stop: () => dashboard.stop() },
+				],
+				channels: [
+					agentClaim({
+						owner: options.owner,
+						speakers: options.speakers,
+						team: built,
+						runtime: running,
+						surface,
+						attachmentDir,
+						logger,
+					}),
+				],
+				http: [discord.studio.route(options.avatarListener)],
+				sessionTools: agentSessionTools(built),
+				events: {
+					agentServer: (outcome) => {
+						options.errorReporter?.connect({
+							channelOf: (name) => {
+								const agent = stores.agents.agent(name);
+								return agent?.status === "active" && agent.channelId
+									? channelKey(agent.channelId)
+									: undefined;
+							},
+							post: (channel, text) =>
+								surface.sendReply(channel, { chunks: splitReply(text) }),
+							turn: (channel, text) =>
+								context.core.background.runErrorReport(channel, text),
+							logger,
+						});
+						if (outcome === "ready") dashboard.start();
+					},
+				},
+			};
+		},
+	};
+}

package/src/core/builtin/discord.ts

@@ -0,0 +1,95 @@
+import { join } from "node:path";
+import { AvatarStudio } from "../agents/avatar-studio.ts";
+import { DiscordSurface } from "../discord/discord-surface.ts";
+import { DispatchThreads } from "../discord/dispatch-threads.ts";
+import { OwnerCards } from "../discord/owner-cards.ts";
+import { OwnerGuard } from "../discord/owner-command.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import type { SpeakerPolicy } from "../speakers.ts";
+
+export interface DiscordOptions {
+	token: string;
+	ownerId: string;
+	/** How the owner is named in audit-log reasons and refusals. */
+	ownerName: string;
+	/** Who may answer a card besides the owner. */
+	speakers: SpeakerPolicy;
+	dataDir: string;
+	/** The origin the agents' pictures are served from. */
+	avatarUrl: string;
+	/** The name of the root slash command, without the slash. */
+	rootCommand: string;
+	/** The assistant's neutral avatar: the style reference and the picture of an agent without one. */
+	avatarReference: string;
+}
+
+/**
+ * The Discord connection and what stands on it: the avatar studio, the owner's cards, the owner
+ * guard, and the threads that carry background reports. It starts the surface, and the channel
+ * queue joins the shutdown drain.
+ */
+export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
+	let commands: DiscordSurface | undefined;
+	return {
+		name: "discord",
+		// Discord registers the commands as it connects, so they go to the surface before it starts.
+		useCommands: (composed) => commands?.useInteractions(composed),
+		setup: async ({ queue, conversations, providers, core, logger }) => {
+			const studio = new AvatarStudio({
+				dir: join(options.dataDir, "avatars"),
+				publicUrl: options.avatarUrl,
+				referencePath: options.avatarReference,
+				draw: providers.images,
+			});
+			await studio.init();
+			// The surface exists by the time a turn posts a card.
+			const cards: OwnerCards = new OwnerCards({
+				ownerId: options.ownerId,
+				speakers: options.speakers,
+				channel: (channelId) => surface.cardChannel(channelId),
+				logger,
+			});
+			const surface = new DiscordSurface({
+				token: options.token,
+				ownerId: options.ownerId,
+				ownerName: options.ownerName,
+				logger,
+			});
+			const guard = new OwnerGuard(
+				options.ownerId,
+				logger,
+				options.rootCommand,
+			);
+			// A channel whose owner keeps reports in place, such as a party channel, opens no thread.
+			const threads = new DispatchThreads({
+				host: {
+					open: (parentId, name, line) =>
+						surface.threadHost().open(parentId, name, line),
+					post: (threadId, text) => surface.threadHost().post(threadId, text),
+					close: (threadId) => surface.threadHost().close(threadId),
+				},
+				ledgerPath: join(options.dataDir, "dispatch-threads.json"),
+				excluded: (channel) => conversations.postsInPlace(channel),
+				logger,
+			});
+			commands = surface;
+			core.provide("discord", { surface, cards, guard, studio, threads });
+			return {
+				services: [
+					{
+						name: "surface",
+						start: async () => {
+							await surface.start(
+								(message) => void conversations.handle(message),
+							);
+							void threads.sweep();
+						},
+						stop: () => surface.stop(),
+					},
+					{ name: "channel-queue", busy: () => queue.busy() },
+				],
+				interactions: [{ module: cards }],
+			};
+		},
+	};
+}

package/src/core/builtin/modules.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "bun:test";
+import type {
+	ExtensionAPI,
+	ExtensionFactory,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type AgentTurnScope,
+	type ChannelKey,
+	compileSessionPlan,
+	type SessionContext,
+} from "../sessions.ts";
+import { OWNER_CHANNEL, setUpModules } from "../testing/modules.ts";
+
+const HOME: ChannelKey = "discord:scout";
+const GROUP: ChannelKey = "discord:war-room";
+const OUTSIDE: ChannelKey = "party:table-1";
+
+const scout: AgentTurnScope = { name: "scout", session: HOME, home: HOME };
+const seat: AgentTurnScope = {
+	name: "scout",
+	session: GROUP,
+	home: HOME,
+	group: "war-room",
+};
+
+function context(agent?: AgentTurnScope, home?: ChannelKey): SessionContext {
+	const session: SessionContext = {
+		kind: agent ? "agent" : "owner",
+		homeChannel: home ?? agent?.home ?? OWNER_CHANNEL,
+		turnChannel: agent?.session ?? home ?? OWNER_CHANNEL,
+		compaction: { wrap: (compactor) => compactor },
+		speaker: () => undefined,
+		runTask: async () => "report",
+	};
+	if (agent) session.agent = agent;
+	return session;
+}
+
+interface Registered {
+	name: string;
+	parameters: { properties: Record<string, unknown> };
+	execute(
+		id: string,
+		params: unknown,
+	): Promise<{ content: { text: string }[]; isError?: boolean }>;
+}
+
+/** The tools one of the modules' extensions registers in a session. */
+async function registered(
+	setup: Awaited<ReturnType<typeof setUpModules>>,
+	session: SessionContext,
+	extension: string,
+): Promise<Registered[]> {
+	const tool = setup.contribution.sessionTools?.find(
+		(candidate) => candidate.name === extension,
+	);
+	const factory: ExtensionFactory | null | undefined = tool
+		?.snapshot()
+		.factory(session);
+	if (!factory) throw new Error(`no ${extension} extension`);
+	const tools: Registered[] = [];
+	await factory({
+		registerTool: (definition: Registered) => tools.push(definition),
+		on: () => undefined,
+	} as unknown as ExtensionAPI);
+	return tools;
+}
+
+describe("modulesPlugin", () => {
+	test("adds the owner's tools in a fixed order, and the delegator to the shutdown drain", async () => {
+		const setup = await setUpModules();
+		const { sessionTools, services } = setup.contribution;
+		expect(sessionTools?.map((tool) => tool.name)).toEqual([
+			"owner-memory",
+			"notify",
+			"schedules",
+			"delegate",
+			"discord-admin",
+		]);
+		expect(sessionTools?.every((tool) => tool.phase === "tools")).toBe(true);
+		expect(services?.map((service) => service.name)).toEqual(["delegator"]);
+		expect(compileSessionPlan(sessionTools ?? []).tools).toHaveLength(5);
+	});
+
+	test("provides the background turns and the delegator to the plugins after it", async () => {
+		const { core } = await setUpModules();
+		expect(core.background).toBeDefined();
+		expect(core.delegator.runningChannels()).toEqual([]);
+	});
+
+	test("delegate_task reports home and opens its thread in the group", async () => {
+		const setup = await setUpModules();
+		const [delegate] = await registered(setup, context(seat), "delegate");
+		await delegate?.execute("1", { title: "t", task: "look it up" });
+		await setup.core.delegator.idle();
+		expect(setup.record.reportChannels).toEqual([HOME]);
+		expect(setup.record.threadOrigins).toEqual([GROUP]);
+		expect(setup.record.ownerChannelAsked).toBe(0);
+	});
+
+	test("a conversation without a chat channel reports in the owner's messages", async () => {
+		const setup = await setUpModules();
+		const [delegate] = await registered(
+			setup,
+			context(undefined, OUTSIDE),
+			"delegate",
+		);
+		await delegate?.execute("1", { title: "t", task: "look it up" });
+		await setup.core.delegator.idle();
+		expect(setup.record.reportChannels).toEqual([OWNER_CHANNEL]);
+		expect(setup.record.ownerChannelAsked).toBe(1);
+	});
+
+	test("only agent sessions may read another agent's schedules", async () => {
+		const setup = await setUpModules({ agentChannelOf: () => HOME });
+		const list = async (session: SessionContext) =>
+			(await registered(setup, session, "schedules")).find(
+				(tool) => tool.name === "schedule_list",
+			);
+		expect(
+			Object.keys((await list(context(scout)))?.parameters.properties ?? {}),
+		).toContain("agent");
+		expect(
+			Object.keys((await list(context()))?.parameters.properties ?? {}),
+		).not.toContain("agent");
+	});
+});