pi-roundtable 0.1.0

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

@@ -0,0 +1,323 @@
+import type { TurnAttachments } from "../domain/attachment.ts";
+import type {
+	ChannelKey,
+	PendingConfirmation,
+	TurnResult,
+} from "../domain/conversation.ts";
+import { AgentError } from "../domain/errors.ts";
+import type { AgentTurnScope } from "../domain/ports.ts";
+import { messages } from "../i18n/index.ts";
+import { splitReply } from "../presentation/reply-splitter.ts";
+import { thinkingLine } from "../presentation/thinking-line.ts";
+import { settleTurn } from "../routing/settle-turn.ts";
+import type { Speaker } from "../speakers.ts";
+import { toolTiers } from "../tool-tiers.ts";
+import { AgentMessages } from "./agent-messages.ts";
+import type { Agent } from "./agent-store.ts";
+import { GroupTurns } from "./group-turns.ts";
+import {
+	channelIdOf,
+	channelKey,
+	channelOwner,
+	homeScope,
+} from "./team-keys.ts";
+import {
+	type Chain,
+	MAX_CHAIN_MESSAGES,
+	type TeamTurnsOptions,
+	type TurnExtra,
+	type TurnHost,
+} from "./team-turn-types.ts";
+
+export { MAX_CHAIN_MESSAGES, type TeamTurnsOptions };
+
+/**
+ * The agent team's turns: owner messages, background turns, group rounds, and messages between
+ * agents, each posted under the answering agent's name.
+ */
+export class TeamTurns {
+	readonly #options: TeamTurnsOptions;
+	/** The chain of each running turn, by session key, read by message_agent. */
+	readonly #chains = new Map<ChannelKey, Chain>();
+	/** The channel each working agent's turn posts in. */
+	readonly #working = new Map<string, ChannelKey>();
+	/** When each agent or group (by `group:<name>`) last started or ended a turn. */
+	readonly #lastActive = new Map<string, Date>();
+
+	readonly #messages: AgentMessages;
+	readonly #groups: GroupTurns;
+
+	constructor(options: TeamTurnsOptions) {
+		this.#options = options;
+		const host: TurnHost = {
+			options,
+			chains: this.#chains,
+			turn: (agent, scope, postTo, text, chain, extra) =>
+				this.#turn(agent, scope, postTo, text, chain, extra),
+			post: (channel, as, body) => this.#post(channel, as, body),
+			current: (agent) => this.#current(agent),
+			mayApprove: (speaker, pending) => this.#mayApprove(speaker, pending),
+			turnChannel: (scope) => this.turnChannel(scope),
+		};
+		this.#messages = new AgentMessages(host);
+		this.#groups = new GroupTurns(host);
+	}
+
+	/** The channel of the agent's running turn, if it has one. */
+	workingIn(agent: string): ChannelKey | undefined {
+		return this.#working.get(agent);
+	}
+
+	/** Whoever started the run the agent's session is in; undefined outside a turn. */
+	speakerOf(scope: AgentTurnScope): Speaker | undefined {
+		return this.#chains.get(scope.session)?.speaker;
+	}
+
+	lastActive(agent: string): Date | undefined {
+		return this.#lastActive.get(agent);
+	}
+
+	lastGroupActive(group: string): Date | undefined {
+		return this.#lastActive.get(`group:${group}`);
+	}
+
+	/**
+	 * The owner's message in an agent's channel; call inside the channel's queue. `text`
+	 * carries the reference, `replyText` is what he typed.
+	 */
+	async answerOwner(
+		channel: ChannelKey,
+		speaker: Speaker,
+		text: string,
+		replyText: string,
+		attachments: TurnAttachments,
+	): Promise<TurnResult> {
+		const agent = this.#agentOf(channel);
+		const scope = homeScope(agent);
+		const pending = await this.#options.runtime().heldActions(scope.session);
+		const confirmed =
+			pending !== undefined &&
+			this.#mayApprove(speaker, pending) &&
+			(await this.#options.confirmations.approves(pending, replyText));
+		return this.#turn(
+			agent,
+			scope,
+			channel,
+			text,
+			{ messages: 0, speaker },
+			{
+				attachments,
+				confirmed,
+				steerable: true,
+				interactive: true,
+			},
+		);
+	}
+
+	/**
+	 * A turn in an agent's channel that no owner message started; call inside its queue. A report
+	 * turn is interactive: it may ask the owner on cards there.
+	 */
+	answerBackground(
+		channel: ChannelKey,
+		speaker: Speaker,
+		text: string,
+		interactive = false,
+	): Promise<TurnResult> {
+		const agent = this.#agentOf(channel);
+		return this.#turn(
+			agent,
+			homeScope(agent),
+			channel,
+			text,
+			{ messages: 0, speaker },
+			interactive ? { interactive: true } : {},
+		);
+	}
+
+	/** Whether the speaker's tier holds every tool of the held actions. */
+	#mayApprove(speaker: Speaker, pending: PendingConfirmation): boolean {
+		const tiers = this.#options.toolTiers ?? toolTiers();
+		return pending.calls.every((call) => tiers.allows(speaker.tier, call.tool));
+	}
+
+	#agentOf(channel: ChannelKey): Agent {
+		const agent = this.#options.store.agentByChannel(channelIdOf(channel));
+		if (!agent) throw new AgentError(`no agent owns ${channel}`);
+		return agent;
+	}
+
+	/**
+	 * Runs one agent turn and posts its reply, or a failure notice, in `postTo` under the
+	 * agent's name. Never rejects.
+	 */
+	async #turn(
+		agent: Agent,
+		scope: AgentTurnScope,
+		postTo: ChannelKey,
+		text: string,
+		chain: Chain,
+		extra: TurnExtra = {},
+	): Promise<TurnResult> {
+		const { logger, startTyping, showStop } = this.#options;
+		const stopTyping = startTyping(postTo);
+		// A group round has several sessions; only an agent's own channel maps to one.
+		const hideStop = scope.group ? undefined : showStop(postTo);
+		this.#chains.set(scope.session, chain);
+		this.#working.set(agent.name, postTo);
+		this.#active(agent.name, scope.group);
+		const turn = {
+			agent: agent.name,
+			channel: postTo,
+			speaker: chain.speaker,
+			...(scope.group ? { group: scope.group } : {}),
+		};
+		this.#options.events?.turnStarted(turn);
+		let result: TurnResult;
+		try {
+			result = await settleTurn(
+				() =>
+					this.#options.runtime().runTurn({
+						channel: postTo,
+						selection: this.#options.selection(scope),
+						text,
+						...(extra.attachments ? { attachments: extra.attachments } : {}),
+						...(extra.confirmed ? { confirmed: true } : {}),
+						...(extra.steerable ? { steerable: true } : {}),
+						...(extra.interactive ? { interactive: true } : {}),
+						agent: scope,
+						speaker: chain.speaker,
+					}),
+				"agent turn",
+			);
+		} finally {
+			hideStop?.();
+			this.#chains.delete(scope.session);
+			this.#working.delete(agent.name);
+			this.#active(agent.name, scope.group);
+		}
+		this.#options.events?.turnEnded({
+			...turn,
+			result: result.ok ? "ok" : result.stopped ? "stopped" : "failed",
+		});
+		try {
+			if (!result.ok && !result.stopped) {
+				logger.error(
+					{ agent: agent.name, channel: postTo, err: result.error },
+					"agent turn failed",
+				);
+			}
+			const thinking =
+				result.ok && result.thinking
+					? thinkingLine(result.thinking)
+					: undefined;
+			await this.#post(postTo, this.#current(agent), {
+				...(thinking ? { thinking } : {}),
+				chunks: result.ok
+					? splitReply(result.text)
+					: [
+							result.stopped
+								? messages().stoppedNotice
+								: messages().failureNotice,
+						],
+			});
+		} catch (error) {
+			logger.error({ agent: agent.name, err: error }, "agent reply not posted");
+		} finally {
+			stopTyping();
+		}
+		return result;
+	}
+
+	#active(agent: string, group: string | undefined): void {
+		const now = new Date();
+		this.#lastActive.set(agent, now);
+		if (group) this.#lastActive.set(`group:${group}`, now);
+		this.#options.changed();
+	}
+
+	/** The agent's latest row, so a display name or avatar changed during the turn shows. */
+	#current(agent: Agent): Agent {
+		return this.#options.store.agent(agent.name) ?? agent;
+	}
+
+	/**
+	 * Posts under the agent's name. A channel no agent or group owns any more, archived while a
+	 * turn ran, gets nothing, so its webhook is not made again.
+	 */
+	async #post(
+		channel: ChannelKey,
+		as: Agent,
+		body: { thinking?: string; chunks: string[]; threadId?: string },
+	): Promise<void> {
+		const { store, channels, studio, logger } = this.#options;
+		if (!channelOwner(store, channel)) {
+			logger.info(
+				{ channel, agent: as.name },
+				"post to an archived channel dropped",
+			);
+			return;
+		}
+		return channels.post(channelIdOf(channel), {
+			name: as.displayName,
+			avatarUrl: studio.url(as.avatarHash),
+			...body,
+		});
+	}
+
+	/**
+	 * Posts text under the caller's name in the channel of its turn: the group's in a group
+	 * round, otherwise its own, as a change report is (repos-and-skills spec behavior 10).
+	 */
+	async postAs(caller: AgentTurnScope, text: string): Promise<void> {
+		const agent = this.#options.store.activeAgent(caller.name);
+		await this.#post(this.turnChannel(caller), this.#current(agent), {
+			chunks: splitReply(text),
+		});
+	}
+
+	/** The channel the scope's turns run in: the group's in a group round, otherwise its own. */
+	turnChannel(scope: AgentTurnScope): ChannelKey {
+		const group = scope.group
+			? this.#options.store.group(scope.group)
+			: undefined;
+		return group ? channelKey(group.channelId) : scope.home;
+	}
+
+	/** The assistant's own notice, such as a new release, posted in the coordinator's channel under its name. */
+	async announce(text: string): Promise<void> {
+		const { store, entryChannelId } = this.#options;
+		const coordinator = store.agentByChannel(entryChannelId);
+		if (!coordinator)
+			throw new AgentError("no active agent in the entry channel");
+		await this.#post(channelKey(entryChannelId), coordinator, {
+			chunks: splitReply(text),
+		});
+	}
+
+	message(caller: AgentTurnScope, to: string, text: string): string {
+		return this.#messages.message(caller, to, text);
+	}
+
+	/**
+	 * 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.
+	 */
+	answerGroup(
+		channel: ChannelKey,
+		speaker: Speaker,
+		text: string,
+		replyText: string,
+		attachments: TurnAttachments,
+		repliedToName: string | undefined,
+	): Promise<void> {
+		return this.#groups.answerGroup(
+			channel,
+			speaker,
+			text,
+			replyText,
+			attachments,
+			repliedToName,
+		);
+	}
+}

package/src/core/assets/prompts/shared-guest.md

@@ -0,0 +1,11 @@
+You are an agent in a Discord server. The person you are talking with is a guest of that server, named in the last section of this prompt. You are not speaking for the server's owner, and the owner's private facts stay theirs.
+
+Reply in the language they write in. Be warm, direct, and brief.
+
+Write in Discord's Markdown: bold, italics, headings, bullet and numbered lists, block quotes, inline code, fenced code blocks, and `-#` small text all render. Discord shows Markdown tables as raw pipes, so list figures as bullets instead.
+
+Your context holds only their own core facts and upcoming events. When a request touches their projects, people, tools, or past, search memory first. When they ask you to remember or forget something, use the memory tools; what you store is theirs alone.
+
+When you need their decision to continue, ask with ask_user instead of ending your turn with a question; they answer on buttons in the channel and your turn goes on.
+
+Cite the source links of web information you use.

package/src/core/assets/prompts/shared.md

@@ -0,0 +1,11 @@
+You are an agent in a Discord server, working for the server's owner. You talk with them in channels and threads.
+
+Reply in the language they write in. Be warm, direct, and brief.
+
+Write in Discord's Markdown: bold, italics, headings, bullet and numbered lists, block quotes, inline code, fenced code blocks, and `-#` small text all render. Discord shows Markdown tables as raw pipes, so list figures as bullets instead.
+
+Your context holds only their core facts and upcoming events. When a request touches their projects, people, tools, or past, search memory first. When they ask you to remember or forget something, use the memory tools.
+
+When you need their decision to continue, ask with ask_user instead of ending your turn with a question; they answer on buttons in the channel and your turn goes on.
+
+Cite the source links of web information you use.

package/src/core/assets/skills/writing-skills/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: writing-skills
+description: Use when creating, editing, or reviewing a skill, or when a lesson from your work should become one.
+---
+
+# Writing Skills
+
+A skill makes the next run predictable: same process, straight to the work. Write the smallest skill that does that.
+
+## Steps
+
+1. **Check the registry.** Run `skill_list` with a word from the task. Extend the skill that owns the procedure instead of adding a second one. A linked skill is read-only here: change it in its repository.
+   - **Completion criterion**: you can name the skill you will create or edit, and why no other one owns this.
+2. **Write the description.** State only when to use the skill: `Use when <trigger>`, one trigger per distinct way it is used, joined with "or". Leave out what the skill does and how.
+   - **Completion criterion**: every phrase in it is a situation that should load the skill.
+3. **Write the body.** Ordered steps, each an action with a checkable **completion criterion**; then the reference the steps need (rules, tables, templates). State the behavior you want; keep a prohibition only as a hard guardrail, paired with what to do instead. Name the tools the agent actually has.
+   - **Completion criterion**: an agent that reads only this body can run the procedure without asking what a step means.
+4. **Cut.** Read each sentence alone and delete it when the model would behave the same without it. One fact lives in one place: point to another skill instead of copying it. A skill an agent writes is a single file of at most 12,000 characters.
+   - **Completion criterion**: every remaining sentence changes behavior.
+5. **Save and attach.** `skill_create` or `skill_update` with the name, description, and body; the tool writes the frontmatter. Attach it with `agent_skills` to the agents that do the work, yourself included when you do.
+   - **Completion criterion**: the tool confirmed the save, and `skill_list` shows the intended carriers.

package/src/core/attachments/attachment-dir.ts

@@ -0,0 +1,15 @@
+import { join } from "node:path";
+import type { ChannelKey } from "../domain/conversation.ts";
+
+/** A channel key as a single path segment. */
+export function channelSegment(channel: ChannelKey): string {
+	return channel.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+
+/** Where an owner channel's attachments are saved; the runtime's read_attachment reads the same place. */
+export function ownerAttachmentDir(
+	dataDir: string,
+	channel: ChannelKey,
+): string {
+	return join(dataDir, "attachments", channelSegment(channel));
+}

package/src/core/attachments/attachment-fetcher.ts

@@ -0,0 +1,83 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type {
+	AttachmentFailure,
+	AttachmentRef,
+	StoredAttachment,
+} from "../domain/attachment.ts";
+
+export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+
+export interface FetchRequest {
+	refs: readonly AttachmentRef[];
+	/** Directory of the channel's attachment store; created when missing. */
+	dir: string;
+	/** Prefix that keeps files of different messages apart, such as the message ID. */
+	prefix: string;
+	fromReference: boolean;
+}
+
+export interface FetchResult {
+	files: StoredAttachment[];
+	failures: AttachmentFailure[];
+}
+
+/** Keeps a file name readable while removing path separators and control characters. */
+export function safeFileName(name: string): string {
+	const cleaned = name
+		.normalize("NFC")
+		.replace(/[/\\\p{Cc}]/gu, "_")
+		.replace(/^\.+/, "_")
+		.slice(-120);
+	return cleaned || "file";
+}
+
+/** Downloads attachments one by one; a failed file is reported without stopping the others. */
+export async function fetchAttachments(
+	request: FetchRequest,
+	fetchImpl: typeof fetch = fetch,
+): Promise<FetchResult> {
+	const files: StoredAttachment[] = [];
+	const failures: AttachmentFailure[] = [];
+	const { refs, dir, prefix, fromReference } = request;
+	if (refs.length === 0) return { files, failures };
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+	for (const [index, ref] of refs.entries()) {
+		const fail = (reason: string) =>
+			failures.push({ name: ref.name, reason, fromReference });
+		if (ref.size > MAX_ATTACHMENT_BYTES) {
+			fail(`larger than 25 MB (${ref.size} bytes)`);
+			continue;
+		}
+		try {
+			const response = await fetchImpl(ref.url);
+			if (!response.ok) {
+				fail(`download failed with HTTP ${response.status}`);
+				continue;
+			}
+			const data = new Uint8Array(await response.arrayBuffer());
+			if (data.byteLength > MAX_ATTACHMENT_BYTES) {
+				fail(`larger than 25 MB (${data.byteLength} bytes)`);
+				continue;
+			}
+			const file = `${prefix}-${index}-${safeFileName(ref.name)}`;
+			const path = join(dir, file);
+			await Bun.write(path, data);
+			files.push({
+				name: ref.name,
+				file,
+				path,
+				contentType:
+					ref.contentType ||
+					response.headers.get("content-type") ||
+					"application/octet-stream",
+				size: data.byteLength,
+				fromReference,
+			});
+		} catch (error) {
+			fail(`download failed: ${String(error)}`);
+		}
+	}
+	return { files, failures };
+}

package/src/core/attachments/attachments.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createCanvas, loadImage } from "canvas";
+import { NO_ATTACHMENTS } from "../domain/attachment.ts";
+import { readAttachment } from "../shared/attachment-reader.ts";
+import { safeFileName } from "./attachment-fetcher.ts";
+import { prepareImage } from "./image-prep.ts";
+import { withAttachmentsBlock } from "./prompt-block.ts";
+
+const dir = mkdtempSync(join(tmpdir(), "roundtable-read-"));
+
+describe("safeFileName", () => {
+	test("keeps names readable and strips path parts", () => {
+		expect(safeFileName("отчёт v2.pdf")).toBe("отчёт v2.pdf");
+		expect(safeFileName("../../etc/passwd")).toBe("__.._etc_passwd");
+		expect(safeFileName("")).toBe("file");
+	});
+});
+
+describe("prepareImage", () => {
+	test("an image over the side limit is downscaled to 2,000 px JPEG", async () => {
+		const canvas = createCanvas(9000, 100);
+		const path = join(dir, "wide.png");
+		await Bun.write(path, canvas.toBuffer("image/png"));
+		const image = await prepareImage({ path, contentType: "image/png" });
+		expect(image.mimeType).toBe("image/jpeg");
+		const decoded = await loadImage(Buffer.from(image.data, "base64"));
+		expect(decoded.width).toBe(2000);
+	});
+});
+
+describe("readAttachment", () => {
+	test("reads text in pieces and refuses paths and binaries", async () => {
+		await Bun.write(join(dir, "a.txt"), "x".repeat(70_000));
+		const first = await readAttachment(dir, "a.txt");
+		expect(first.text).toHaveLength(60_000);
+		expect(first.total).toBe(70_000);
+		expect((await readAttachment(dir, "a.txt", 60_000)).text).toHaveLength(
+			10_000,
+		);
+		await expect(readAttachment(dir, "../a.txt")).rejects.toThrow(
+			"not an attachment name",
+		);
+		await Bun.write(join(dir, "b.bin"), new Uint8Array([0, 1, 2, 255]));
+		await expect(readAttachment(dir, "b.bin")).rejects.toThrow(
+			"not a text or PDF file",
+		);
+		await expect(readAttachment(dir, "none.txt")).rejects.toThrow(
+			"no attachment named",
+		);
+	});
+});
+
+describe("withAttachmentsBlock", () => {
+	test("adds nothing without attachments", () => {
+		expect(withAttachmentsBlock("hi", NO_ATTACHMENTS)).toBe("hi");
+	});
+
+	test("lists files and failures", () => {
+		const text = withAttachmentsBlock("hi", {
+			files: [
+				{
+					name: "a.pdf",
+					file: "m-0-a.pdf",
+					path: "/x",
+					contentType: "application/pdf",
+					size: 2048,
+					fromReference: false,
+				},
+			],
+			images: [],
+			failures: [
+				{ name: "b.mov", reason: "larger than 25 MB", fromReference: true },
+			],
+		});
+		expect(text).toContain(
+			'- m-0-a.pdf (original name "a.pdf", application/pdf, 2 KB)',
+		);
+		expect(text).toContain(
+			'"b.mov" from the replied-to message could not be received: larger than 25 MB',
+		);
+	});
+});

package/src/core/attachments/image-prep.ts

@@ -0,0 +1,50 @@
+import { createCanvas, loadImage } from "canvas";
+import type { ModelImage, StoredAttachment } from "../domain/attachment.ts";
+
+/** Images the model accepts as images; other files stay files. */
+const IMAGE_TYPES = new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp",
+]);
+export const MAX_IMAGES_PER_TURN = 4;
+/** Base64 grows by a third, so 3.75 MB stays under Claude's 5 MB per image. */
+const MAX_RAW_BYTES = 3.75 * 1024 * 1024;
+const MAX_SIDE = 8000;
+const DOWNSCALED_SIDE = 2000;
+
+export function isModelImage(
+	file: Pick<StoredAttachment, "contentType">,
+): boolean {
+	return IMAGE_TYPES.has(
+		file.contentType.split(";")[0]?.trim().toLowerCase() ?? "",
+	);
+}
+
+/**
+ * Returns the image as the model accepts it. An image over the size or side limit is
+ * re-encoded as JPEG with its long side at 2,000 px instead of being dropped.
+ */
+export async function prepareImage(
+	file: Pick<StoredAttachment, "path" | "contentType">,
+): Promise<ModelImage> {
+	const bytes = Buffer.from(await Bun.file(file.path).arrayBuffer());
+	const mimeType = file.contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+	if (bytes.byteLength <= MAX_RAW_BYTES) {
+		const image = await loadImage(bytes);
+		if (Math.max(image.width, image.height) <= MAX_SIDE) {
+			return { data: bytes.toString("base64"), mimeType };
+		}
+	}
+	const image = await loadImage(bytes);
+	const scale = DOWNSCALED_SIDE / Math.max(image.width, image.height);
+	const width = Math.max(1, Math.round(image.width * Math.min(1, scale)));
+	const height = Math.max(1, Math.round(image.height * Math.min(1, scale)));
+	const canvas = createCanvas(width, height);
+	canvas.getContext("2d").drawImage(image, 0, 0, width, height);
+	return {
+		data: canvas.toBuffer("image/jpeg", { quality: 0.85 }).toString("base64"),
+		mimeType: "image/jpeg",
+	};
+}

package/src/core/attachments/prompt-block.ts

@@ -0,0 +1,37 @@
+import type { TurnAttachments } from "../domain/attachment.ts";
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * Appends an `## Attachments` block naming every file the turn carries, so the model knows
+ * what it can read or hand to tools. Files are named by their store file name, which is what
+ * `read_attachment` and file-taking tools accept.
+ */
+export function withAttachmentsBlock(
+	text: string,
+	attachments: TurnAttachments,
+): string {
+	const lines: string[] = [];
+	for (const file of attachments.files) {
+		const origin = file.fromReference ? ", from the replied-to message" : "";
+		lines.push(
+			`- ${file.file} (original name "${file.name}", ${file.contentType}, ${formatSize(file.size)}${origin})`,
+		);
+	}
+	for (const failure of attachments.failures) {
+		const origin = failure.fromReference ? " from the replied-to message" : "";
+		lines.push(
+			`- "${failure.name}"${origin} could not be received: ${failure.reason}`,
+		);
+	}
+	if (lines.length === 0) return text;
+	const note =
+		attachments.images.length > 0
+			? "Images among them are shown to you directly. Read other files with read_attachment."
+			: "Read them with read_attachment.";
+	return `${text}\n\n## Attachments\n${note}\n${lines.join("\n")}`;
+}