pi-roundtable 0.6.1 → 0.7.2

package/src/core/reply-files.ts

@@ -0,0 +1,107 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { ReplyFile, TurnResult } from "./domain/conversation.ts";
+
+/** Limits across all tools in one turn, independent of the surface's own limits. */
+export const REPLY_FILE_LIMITS = Object.freeze({
+	maxFiles: 10,
+	maxFileBytes: 10 * 1024 * 1024,
+	maxTotalBytes: 50 * 1024 * 1024,
+});
+
+/** An attachment was refused; its message names the reason instead of dropping the file. */
+export class ReplyFileError extends Error {
+	override name = "ReplyFileError";
+}
+
+interface ReplyFiles {
+	active: boolean;
+	supported: boolean;
+	files: ReplyFile[];
+	bytes: number;
+}
+
+const current = new AsyncLocalStorage<ReplyFiles | undefined>();
+
+/**
+ * Queues a copy of a file for the current turn's successful reply. Session tools and Pi package
+ * tools may call this directly; outside a supported running turn it throws ReplyFileError.
+ */
+export function attachReplyFile(file: ReplyFile): void {
+	const turn = current.getStore();
+	if (!turn?.active)
+		throw new ReplyFileError(
+			"attachReplyFile requires a running conversation turn; await it inside the turn's tool call.",
+		);
+	if (!turn.supported)
+		throw new ReplyFileError(
+			"this turn's chat surface does not support reply files.",
+		);
+	if (
+		!file ||
+		typeof file.name !== "string" ||
+		!file.name.trim() ||
+		file.name.length > 255 ||
+		/[\\/]/.test(file.name) ||
+		[...file.name].some(
+			(char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+		) ||
+		file.name === "." ||
+		file.name === ".."
+	)
+		throw new ReplyFileError(
+			"a reply file needs a non-empty filename of at most 255 characters, without paths or control characters.",
+		);
+	if (!(file.data instanceof Uint8Array) || file.data.byteLength === 0)
+		throw new ReplyFileError("a reply file needs non-empty Uint8Array data.");
+	if (turn.files.length >= REPLY_FILE_LIMITS.maxFiles)
+		throw new ReplyFileError(
+			`a turn may attach at most ${REPLY_FILE_LIMITS.maxFiles} reply files.`,
+		);
+	if (file.data.byteLength > REPLY_FILE_LIMITS.maxFileBytes)
+		throw new ReplyFileError(
+			`a reply file may contain at most ${REPLY_FILE_LIMITS.maxFileBytes} bytes.`,
+		);
+	if (turn.bytes + file.data.byteLength > REPLY_FILE_LIMITS.maxTotalBytes)
+		throw new ReplyFileError(
+			`a turn's reply files may contain at most ${REPLY_FILE_LIMITS.maxTotalBytes} bytes in total.`,
+		);
+	turn.files.push({ name: file.name, data: new Uint8Array(file.data) });
+	turn.bytes += file.data.byteLength;
+}
+
+/** Used by test fixtures to forward attachments only when called inside a turn. */
+export function hasReplyFileScope(): boolean {
+	return current.getStore()?.active === true;
+}
+
+/** Whether an otherwise empty final answer has files to show. */
+export function hasReplyFiles(): boolean {
+	const turn = current.getStore();
+	return turn?.active === true && turn.files.length > 0;
+}
+
+/** One isolated collector per turn, also when turns run concurrently or nest. */
+export async function withReplyFiles(
+	supported: boolean,
+	run: () => Promise<TurnResult>,
+): Promise<TurnResult> {
+	const turn: ReplyFiles = { active: true, supported, files: [], bytes: 0 };
+	return current.run(turn, async () => {
+		try {
+			const result = await run();
+			if (!result.ok) return result;
+			// A replacement runtime may produce files in its result rather than calling the helper.
+			for (const file of result.files ?? []) attachReplyFile(file);
+			return turn.files.length ? { ...result, files: [...turn.files] } : result;
+		} finally {
+			turn.active = false;
+			turn.files = [];
+			turn.bytes = 0;
+		}
+	});
+}
+
+/** A transient task reports text, not a conversation reply: it cannot borrow its parent's collector. */
+export function withoutReplyFiles<T>(run: () => Promise<T>): Promise<T> {
+	return current.run(undefined, run);
+}

package/src/core/routing/conversation-turns.ts

@@ -7,6 +7,7 @@ import type { Logger } from "../log.ts";
 import type { EventSink } from "../plugin.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
 import { thinkingLine } from "../presentation/thinking-line.ts";
+import { withReplyFiles } from "../reply-files.ts";
 import type { ChannelKey, ToolSelection, TurnSelection } from "../sessions.ts";
 import type { Speaker } from "../speakers.ts";
 import { endOf, settleTurn } from "./settle-turn.ts";
@@ -85,20 +86,24 @@ export function conversationTurns(
 			try {
 				result = await settleTurn(
 					() =>
-						runtime.runTurn({
-							channel,
-							kind,
-							selection: input.selection ?? {
-								id: DEFAULT_SELECTION,
-								...options.selection(),
-							},
-							text: input.text,
-							speaker,
-							...(input.attachments ? { attachments: input.attachments } : {}),
-							...(input.confirmed ? { confirmed: true } : {}),
-							...(input.steerable ? { steerable: true } : {}),
-							...(input.interactive ? { interactive: true } : {}),
-						}),
+						withReplyFiles(surfaces.of(channel)?.supportsFiles === true, () =>
+							runtime.runTurn({
+								channel,
+								kind,
+								selection: input.selection ?? {
+									id: DEFAULT_SELECTION,
+									...options.selection(),
+								},
+								text: input.text,
+								speaker,
+								...(input.attachments
+									? { attachments: input.attachments }
+									: {}),
+								...(input.confirmed ? { confirmed: true } : {}),
+								...(input.steerable ? { steerable: true } : {}),
+								...(input.interactive ? { interactive: true } : {}),
+							}),
+						),
 					"conversation turn",
 				);
 			} finally {
@@ -135,5 +140,6 @@ function replyOf(result: TurnResult) {
 	return {
 		...(thinking ? { thinking } : {}),
 		chunks: splitReply(result.text),
+		...(result.files?.length ? { files: result.files } : {}),
 	};
 }

package/src/core/routing/surface-port.ts

@@ -24,8 +24,14 @@ export function surfacePort(linked: () => readonly ChatSurface[]): SurfacePort {
 	};
 	return {
 		of,
-		sendReply: async (channel, reply) =>
-			served(channel).sendReply(channel, reply),
+		sendReply: async (channel, reply) => {
+			const surface = served(channel);
+			if (reply.files?.length && surface.supportsFiles !== true)
+				throw new PluginError(
+					`surface ${surface.surface} does not support reply files; declare supportsFiles: true and deliver every file in sendReply.`,
+				);
+			await surface.sendReply(channel, reply);
+		},
 		startTyping: (channel) =>
 			of(channel)?.startTyping?.(channel) ?? (() => undefined),
 		showStop: (channel) =>

package/src/core/runtime/pi-agent-runtime.ts

@@ -24,6 +24,7 @@ import {
 	type ThinkingLevel,
 	type ThinkingSetting,
 } from "../models.ts";
+import { withoutReplyFiles } from "../reply-files.ts";
 import { planOrder, type TransientTask } from "../sessions.ts";
 import { textOf } from "../shared/session-messages.ts";
 import { addressee, type Speaker, type Tier } from "../speakers.ts";
@@ -352,7 +353,7 @@ export class PiAgentRuntime implements AgentRuntime {
 						this.#tiers.allows(tier, name),
 				);
 			session.setActiveToolsByName([...worker.tools]);
-			await session.prompt(task.text);
+			await withoutReplyFiles(() => session.prompt(task.text));
 			return workerReport(
 				session.messages,
 				"the worker stopped before it reported",

package/src/core/runtime/turn-answer.ts

@@ -1,5 +1,6 @@
 import type { TurnResult } from "../domain/conversation.ts";
 import { AgentRunError } from "../domain/errors.ts";
+import { hasReplyFiles } from "../reply-files.ts";
 import { lastAssistant, textOf } from "../shared/session-messages.ts";
 
 interface MessagePart {
@@ -67,7 +68,7 @@ export function turnAnswer(
 					.join("\n\n")
 			: textOf(last.message.content)
 	).trim();
-	if (!text)
+	if (!text && !hasReplyFiles())
 		return {
 			ok: false,
 			error: new AgentRunError("the final assistant message has no text"),

package/src/index.ts

@@ -77,6 +77,7 @@ export type {
 	HeldCall,
 	OutboundReply,
 	PendingConfirmation,
+	ReplyFile,
 	TranscriptEntry,
 	TurnResult,
 } from "./core/domain/conversation.ts";
@@ -157,6 +158,11 @@ export type {
 	TurnEndEvent,
 	TurnEvent,
 } from "./core/plugin.ts";
+export {
+	attachReplyFile,
+	REPLY_FILE_LIMITS,
+	ReplyFileError,
+} from "./core/reply-files.ts";
 export type {
 	ConversationTurnInput,
 	ConversationTurns,

package/src/testing.ts

@@ -25,7 +25,10 @@ import type {
 	InteractionContribution,
 } from "./core/discord/interaction-module.ts";
 import { OwnerGuard, ownerRootCommand } from "./core/discord/owner-command.ts";
-import type { PendingConfirmation } from "./core/domain/conversation.ts";
+import type {
+	PendingConfirmation,
+	ReplyFile,
+} from "./core/domain/conversation.ts";
 import { NotLinkedError, PluginError } from "./core/errors.ts";
 import { EventBus } from "./core/events.ts";
 import type { HoldCheck } from "./core/holds.ts";
@@ -48,6 +51,11 @@ import {
 } from "./core/registry/contributions.ts";
 import { resolveProviders } from "./core/registry/providers.ts";
 import { ServiceRegistry } from "./core/registry/services.ts";
+import {
+	attachReplyFile,
+	hasReplyFileScope,
+	withReplyFiles,
+} from "./core/reply-files.ts";
 import { ChannelQueue } from "./core/routing/channel-queue.ts";
 import { ChannelRouter } from "./core/routing/channel-router.ts";
 import {
@@ -203,6 +211,8 @@ export interface TestPluginResult {
 	tools: readonly string[];
 	tiers: ToolTierTable;
 	events: RecordedEvent[];
+	/** Files accepted by successful runTool calls, copied and recorded with their channel. */
+	files: { channel: ChannelKey; file: ReplyFile }[];
 	runTool(
 		name: string,
 		args: Record<string, unknown>,
@@ -233,7 +243,10 @@ function unlinked(part: keyof typeof NOT_LINKED): never {
 const PROBED = new Set(["then", "toJSON", "asymmetricMatch"]);
 
 /** A service the test gave only some members of: reading another names the option that adds it. */
-function partialService(key: ServiceKey<unknown>, given: object): object {
+function partialService<T extends object>(
+	key: ServiceKey<unknown>,
+	given: T,
+): T {
 	return new Proxy(given, {
 		get(target, member, receiver) {
 			if (member in target || typeof member === "symbol" || PROBED.has(member))
@@ -495,6 +508,7 @@ export async function testPlugin(
 	for (const surface of options.surfaces ?? []) await surface.start(deliver);
 	await runtime?.preflight?.();
 	let stopped = false;
+	const files: { channel: ChannelKey; file: ReplyFile }[] = [];
 	return {
 		contribution,
 		holds: linked.holds,
@@ -505,6 +519,7 @@ export async function testPlugin(
 		tools: registry.tools.map((tool) => tool.name),
 		tiers,
 		events,
+		files,
 		async runTool(name, args, runOptions) {
 			const tool = registry.tools.find((item) => item.name === name);
 			if (!tool) throw new PluginError(`tool ${name} is not registered`);
@@ -539,8 +554,23 @@ export async function testPlugin(
 			const execute = registered[0]?.execute;
 			if (!execute)
 				throw new PluginError(`tool ${name} did not register in the session`);
-			const result = await execute("test-call", args);
-			return result.content.map((item) => item.text ?? "").join("\n");
+			const result = await withReplyFiles(
+				surfaces.of(channel)?.supportsFiles === true,
+				async () => {
+					const output = await execute("test-call", args);
+					return {
+						ok: true,
+						text: output.content.map((item) => item.text ?? "").join("\n"),
+					};
+				},
+			);
+			if (!result.ok) throw result.error;
+			for (const file of result.files ?? []) {
+				files.push({ channel, file });
+				// When runTool is used by a fake runtime, forward into the enclosing real turn.
+				if (hasReplyFileScope()) attachReplyFile(file);
+			}
+			return result.text;
 		},
 		async stop() {
 			if (stopped) return;

package/templates/biome.json.tmpl

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
 	"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
 	"formatter": { "indentStyle": "tab" },
 	"linter": { "rules": { "preset": "recommended" } },

package/templates/official/release-notice/plugin.test.ts.tmpl

@@ -0,0 +1,248 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENT_SERVER_PLUGIN,
+	AGENT_TEAM_SERVICE,
+	AGENTS,
+	type AgentTeam,
+} from "pi-roundtable";
+import { partial, servicePair, testPlugin } from "pi-roundtable/testing";
+import { createReleaseNotice, noticeText } from "./release-notice.ts";
+
+let dir: string;
+let posted: string[];
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), "release-notice-"));
+	posted = [];
+});
+afterEach(() => rm(dir, { recursive: true, force: true }));
+
+const releaseFile = () => join(dir, "release.json");
+const dataDir = () => join(dir, "data");
+const writeRelease = (sha: string, commits: string[]) =>
+	writeFile(releaseFile(), JSON.stringify({ sha, commits }));
+
+/** The plugin over the temporary directory, posting into `posted`; `fail` makes the post throw. */
+async function started(fail = false) {
+	const harness = await testPlugin(
+		createReleaseNotice({
+			releaseFile: releaseFile(),
+			dataDir: dataDir(),
+			announce: async (text) => {
+				if (fail) throw new Error("the channel is gone");
+				posted.push(text);
+			},
+		}),
+	);
+	const events = harness.contribution.events;
+	return {
+		harness,
+		/** What the host delivers when the agent server's channels are up. */
+		ready: () =>
+			events?.serviceStarted?.({
+				plugin: AGENT_SERVER_PLUGIN,
+				service: AGENT_TEAM_SERVICE,
+				outcome: "ready",
+			}),
+		/** What the host delivers when the shutdown drain ends. */
+		shutdown: (left: string[]) => events?.shutdown?.(left),
+	};
+}
+
+test("a start with no release.json announces nothing", async () => {
+	const run = await started();
+	await run.ready();
+	expect(posted).toEqual([]);
+	await run.harness.stop();
+});
+
+test("a new release is announced once, with its commits", async () => {
+	await writeRelease("abc1234", ["fix: b", "feat: a"]);
+	const first = await started();
+	await first.ready();
+	expect(posted).toEqual(["🔄 Updated to `abc1234`\n- fix: b\n- feat: a"]);
+	await first.harness.stop();
+	// The next start of the same release says nothing.
+	const second = await started();
+	await second.ready();
+	expect(posted).toHaveLength(1);
+	await second.harness.stop();
+	// A different release is announced again.
+	await writeRelease("def5678", ["feat: c"]);
+	const third = await started();
+	await third.ready();
+	expect(posted[1]).toBe("🔄 Updated to `def5678`\n- feat: c");
+	await third.harness.stop();
+});
+
+test("only the agent server's ready event announces", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const harness = await testPlugin(
+		createReleaseNotice({
+			releaseFile: releaseFile(),
+			dataDir: dataDir(),
+			announce: async (text) => {
+				posted.push(text);
+			},
+		}),
+	);
+	const serviceStarted = harness.contribution.events?.serviceStarted;
+	await serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: AGENT_TEAM_SERVICE,
+		outcome: "failed",
+	});
+	await serviceStarted?.({
+		plugin: "other",
+		service: AGENT_TEAM_SERVICE,
+		outcome: "ready",
+	});
+	await serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: "other",
+		outcome: "ready",
+	});
+	expect(posted).toEqual([]);
+	await harness.stop();
+});
+
+test("work a shutdown cut short is reported once, after a restart of the same release", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const first = await started();
+	await first.ready();
+	await first.shutdown(["discord:111", "agentgroup:222.infra", "discord:111"]);
+	const second = await started();
+	await second.ready();
+	expect(posted[1]).toBe(
+		"🔄 Restarted (`abc1234`)\n-# Cut short by the restart, still running when the shutdown wait ended: <#111>, <#222>",
+	);
+	await second.harness.stop();
+	const third = await started();
+	await third.ready();
+	expect(posted).toHaveLength(2);
+	await third.harness.stop();
+});
+
+test("a shutdown that left nothing records nothing", async () => {
+	await writeRelease("abc1234", []);
+	const first = await started();
+	await first.ready();
+	await first.shutdown([]);
+	await first.harness.stop();
+	const second = await started();
+	await second.ready();
+	expect(posted).toHaveLength(1);
+	await second.harness.stop();
+});
+
+test("a post that fails leaves the release unannounced, so the next start tries again", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const failing = await started(true);
+	await expect(failing.ready()).rejects.toThrow("the channel is gone");
+	await failing.harness.stop();
+	expect(await Bun.file(join(dataDir(), "announced-release")).exists()).toBe(
+		false,
+	);
+	const next = await started();
+	await next.ready();
+	expect(posted).toEqual(["🔄 Updated to `abc1234`\n- fix: b"]);
+	await next.harness.stop();
+});
+
+test("a release.json that is not a valid description fails with its path and announces nothing", async () => {
+	for (const bad of [
+		"",
+		"{ not json",
+		"null",
+		"[]",
+		"{}",
+		'{"sha":"","commits":[]}',
+		'{"sha":"abc1234"}',
+		'{"sha":"abc1234","commits":"fix: b"}',
+		'{"sha":"abc1234","commits":["fix: b",null,{}]}',
+	]) {
+		await writeFile(releaseFile(), bad);
+		const run = await started();
+		await expect(run.ready()).rejects.toThrow(
+			`${releaseFile()} is not a valid release description`,
+		);
+		await run.harness.stop();
+	}
+	expect(posted).toEqual([]);
+});
+
+test("a recorded list that is not a list of strings fails with its path", async () => {
+	await writeRelease("abc1234", []);
+	await mkdir(dataDir(), { recursive: true });
+	await writeFile(join(dataDir(), "aborted-on-shutdown.json"), '["a", 1]');
+	const run = await started();
+	await expect(run.ready()).rejects.toThrow("is not a list of strings");
+	await run.harness.stop();
+});
+
+test("a shutdown during the post is not lost, and one that ends before the next start adds to the unannounced", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	let finish = () => {};
+	const harness = await testPlugin(
+		createReleaseNotice({
+			releaseFile: releaseFile(),
+			dataDir: dataDir(),
+			announce: (text) =>
+				new Promise<void>((resolve) => {
+					posted.push(text);
+					finish = resolve;
+				}),
+		}),
+	);
+	const events = harness.contribution.events;
+	const announcing = events?.serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: AGENT_TEAM_SERVICE,
+		outcome: "ready",
+	});
+	// The host shuts down while the notice is still being posted.
+	while (posted.length === 0) await Bun.sleep(1);
+	await events?.shutdown?.(["discord:111"]);
+	finish();
+	await announcing;
+	await events?.shutdown?.(["discord:333"]);
+	await harness.stop();
+	const next = await started();
+	await next.ready();
+	expect(posted[1]).toContain("<#111>, <#333>");
+	await next.harness.stop();
+});
+
+test("without an announce option the notice goes to the agent team", async () => {
+	await writeRelease("abc1234", ["fix: b"]);
+	const harness = await testPlugin(
+		createReleaseNotice({ releaseFile: releaseFile(), dataDir: dataDir() }),
+		{
+			services: [
+				servicePair(AGENTS, {
+					team: partial<AgentTeam>({
+						announce: async (text) => {
+							posted.push(text);
+						},
+					}),
+				}),
+			],
+		},
+	);
+	await harness.contribution.events?.serviceStarted?.({
+		plugin: AGENT_SERVER_PLUGIN,
+		service: AGENT_TEAM_SERVICE,
+		outcome: "ready",
+	});
+	expect(posted).toEqual(["🔄 Updated to `abc1234`\n- fix: b"]);
+	await harness.stop();
+});
+
+test("a channel key that is not Discord's is named as it is", () => {
+	expect(noticeText({ sha: "a", commits: [] }, false, ["slack:C1"])).toContain(
+		"slack:C1",
+	);
+});