pi-roundtable 0.15.4 → 0.17.0

package/src/core/testing/test-host.ts

@@ -1,11 +1,11 @@
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
-	type ExtensionAPI,
 	type ExtensionFactory,
 	SessionManager,
 } from "@earendil-works/pi-coding-agent";
+import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
 import { DISCORD, type DiscordServices } from "../builtin/discord.ts";
 import { type RoundtableConfig, resolveConfig } from "../config/config.ts";
 import type { ConversationPort } from "../contract/channels.ts";
@@ -21,6 +21,7 @@ import type {
 	InteractionContribution,
 } from "../discord/interaction-module.ts";
 import { commandGuard, ownerRootCommand } from "../discord/owner-command.ts";
+import type { HoldDescription } from "../holds.ts";
 import { Roundtable } from "../host.ts";
 import { silentLogger } from "../log.ts";
 import type { PluginContext, RoundtablePlugin } from "../plugin.ts";
@@ -28,9 +29,15 @@ import { CompactionTiers } from "../runtime/compaction-tiers.ts";
 import { privateCompaction } from "../runtime/extensions/private-memory.ts";
 import { sessionExtensions } from "../runtime/runtime-types.ts";
 import { IDENTITY } from "../services.ts";
-import type { AgentTurnScope, SessionContext } from "../sessions.ts";
-import { THE_SPEAKER } from "../speakers.ts";
+import type {
+	AgentTurnScope,
+	ChannelKey,
+	SessionContext,
+} from "../sessions.ts";
+import { type Speaker, THE_SPEAKER } from "../speakers.ts";
+import { toolTurn } from "../tool-turn.ts";
 import { testDatabaseUrl } from "./database.ts";
+import { callRegisteredTool, registeredTools, toolNamed } from "./run-tool.ts";
 
 export interface TestHostOptions {
 	/**
@@ -74,6 +81,26 @@ export interface TestHost {
 	): Promise<{ extension: string; tools: string[] }[]>;
 	/** A session context as the runtime builds it, with the real compaction wrapper. */
 	sessionContext(scope?: AgentTurnScope): SessionContext;
+	/**
+	 * Runs a contributed tool in the owner's session as `speaker` on `channel` (the owner's channel
+	 * by default), as `testPlugin`'s `runTool` does, and gives the text the model would read. A tool
+	 * that throws throws here, a refusal (`ToolRefusal`) comes back as the text the model reads, and a
+	 * tool no plugin added throws a PluginError.
+	 */
+	runTool(
+		name: string,
+		args: Record<string, unknown>,
+		options?: { speaker?: Speaker; channel?: ChannelKey; origin?: string },
+	): Promise<string>;
+	/**
+	 * What the tool's hold would show for the call, asked as a turn of `speaker` on `channel` asks
+	 * it, or undefined when the call runs without an approval.
+	 */
+	hold(
+		name: string,
+		args: Record<string, unknown>,
+		options?: { speaker?: Speaker; channel?: ChannelKey },
+	): Promise<HoldDescription | undefined>;
 	/** Stops the host, services first-started last. */
 	stop(): Promise<void>;
 }
@@ -189,31 +216,6 @@ export function standInDiscord(
 	};
 }
 
-/** Anything an extension may call or read on the Pi API besides registering a tool: accepted, does nothing. */
-type Ignored = (...args: readonly never[]) => Ignored;
-
-function ignored(): Ignored {
-	return new Proxy((() => ignored()) as Ignored, {
-		get: (target, key) => (key === "then" ? undefined : target),
-	});
-}
-
-/** The tools a factory registers, by name; every other registration (handlers, commands, events) is accepted and ignored. */
-async function registeredBy(factory: ExtensionFactory): Promise<string[]> {
-	const names: string[] = [];
-	const registerTool = (tool: { name: string }) => names.push(tool.name);
-	// SAFETY: a session factory only registers tools, handlers and commands; the fake records the tool names and ignores the rest.
-	const api = new Proxy(
-		{},
-		{
-			get: (_target, key) =>
-				key === "registerTool" ? registerTool : ignored(),
-		},
-	) as unknown as ExtensionAPI;
-	await factory(api);
-	return names;
-}
-
 const noop: ExtensionFactory = () => undefined;
 /** The core's own extensions, which a session here does not load: only the plugins' registrations are listed. */
 const CORE_EXTENSIONS = {
@@ -222,6 +224,7 @@ const CORE_EXTENSIONS = {
 	askUser: noop,
 	selfCompactGuard: noop,
 	privateMemory: noop,
+	surfaceFormatting: noop,
 	activeTools: noop,
 };
 
@@ -296,6 +299,26 @@ export async function testHost(
 	const ownerChannel = withDiscord
 		? await (given?.ownerChannel ?? (async () => "discord:owner-dm" as const))()
 		: ("test:owner" as const);
+	let tools: string | undefined;
+	/** The directory the tool runs of this host keep their attachments in; made on the first run. */
+	const attachmentDir = () =>
+		(tools ??= mkdtempSync(join(tmpdir(), "roundtable-test-host-tools-")));
+	/** The owner's session as a tool call of `call` finds it: that speaker on that channel. */
+	const toolSession = (call?: {
+		speaker?: Speaker;
+		channel?: ChannelKey;
+		origin?: string;
+	}): SessionContext => {
+		const channel = call?.channel ?? ownerChannel;
+		return {
+			...sessionContext(),
+			homeChannel: channel,
+			turnChannel: channel,
+			attachmentDir: ownerAttachmentDir(attachmentDir(), channel),
+			speaker: () => call?.speaker,
+			origin: () => call?.origin,
+		};
+	};
 	/** A group seat's turns run in the group's channel; an agent's in its own. */
 	const turnChannelOf = (scope?: AgentTurnScope) =>
 		scope?.group ? scope.session : scope?.home;
@@ -351,13 +374,38 @@ export async function testHost(
 			))
 				tools.push({
 					extension: extension.name,
-					tools: await registeredBy(extension.factory),
+					tools: (await registeredTools(extension.factory)).map(
+						(tool) => tool.name,
+					),
 				});
 			return tools;
 		},
 		sessionContext,
+		runTool: async (name, args, call) => {
+			const channel = call?.channel ?? ownerChannel;
+			const session = toolSession(call);
+			const tools = [];
+			for (const extension of sessionExtensions(
+				context.sessions().plan,
+				session,
+				CORE_EXTENSIONS,
+			))
+				tools.push(...(await registeredTools(extension.factory)));
+			const result = await callRegisteredTool(
+				toolNamed(tools, name),
+				args,
+				context.surfaces.of(channel)?.supportsFiles === true,
+			);
+			return result.text;
+		},
+		hold: async (name, args, call) =>
+			context
+				.sessions()
+				.holds.inTurn?.(name, args, {}, toolTurn(toolSession(call), undefined)),
 		stop: async () => {
 			await roundtable.shutdown("test");
+			if (tools) rmSync(tools, { recursive: true, force: true });
+			tools = undefined;
 		},
 	};
 }

package/src/index.ts

@@ -155,6 +155,7 @@ export type {
 } from "./core/holds.ts";
 export type { HostEnvironment, RoundtableOptions } from "./core/host.ts";
 export { Roundtable } from "./core/host.ts";
+export type { RegistrationReport } from "./core/host-registration.ts";
 export type {
 	HttpRoute,
 	ListenerAddress,

package/src/testing.ts

@@ -1,7 +1,6 @@
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SQL } from "bun";
 import { agentClaim } from "./core/agents/agent-claim.ts";
 import { ownerAttachmentDir } from "./core/attachments/attachment-dir.ts";
@@ -60,11 +59,6 @@ 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 {
@@ -83,6 +77,10 @@ import {
 import type { ChannelKey, SessionContext } from "./core/sessions.ts";
 import { type Speaker, THE_SPEAKER } from "./core/speakers.ts";
 import { mapIdentity } from "./core/testing/map-identity.ts";
+import {
+	callRegisteredTool,
+	registeredTools,
+} from "./core/testing/run-tool.ts";
 import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
 
 // Fixtures for plugin tests.
@@ -92,6 +90,7 @@ export type { TestStore } from "./core/testing/database.ts";
 export {
 	describeDb,
 	openTestStore,
+	requireDatabase,
 	TEST_GUILD,
 	testDatabaseUrl,
 } from "./core/testing/database.ts";
@@ -100,6 +99,8 @@ export type { TestLocale } from "./core/testing/locale.ts";
 export { useTestLocale } from "./core/testing/locale.ts";
 export { OWNER_SPEAKER } from "./core/testing/owner.ts";
 export { partial } from "./core/testing/partial.ts";
+export type { UsePostgresOptions } from "./core/testing/postgres.ts";
+export { usePostgresForTests } from "./core/testing/postgres.ts";
 export type {
 	FakePrecheck,
 	FakePrecheckAnswer,
@@ -447,6 +448,7 @@ export async function testPlugin(
 			sessions: () => linked ?? unlinked("sessions"),
 			toolTiers: tiers,
 			prompts: (channel, speaker) => surfaces.prompts(channel, speaker),
+			formatting: (channel) => surfaces.of(channel)?.formatting,
 			agents: {
 				workDir: tmpdir(),
 				skills: () => [],
@@ -606,6 +608,14 @@ export async function testPlugin(
 	// The plugin's own surfaces start as services; the injected ones start beside them, after.
 	const deliver = (message: InboundMessage) =>
 		void conversations.handle(message);
+	// As the host does, the plugin's preflight runs once everything is set up and before any service starts.
+	try {
+		await plugin.preflight?.();
+	} catch (error) {
+		// The runtime the provider built is not left running when the plugin refuses.
+		await runtime?.dispose?.();
+		throw error;
+	}
 	for (const service of registry.services) await service.start?.();
 	for (const surface of options.surfaces ?? []) await surface.start(deliver);
 	await runtime?.preflight?.();
@@ -627,21 +637,6 @@ export async function testPlugin(
 		async runTool(name, args, runOptions) {
 			const tool = registry.tools.find((item) => item.name === name);
 			if (!tool) throw new PluginError(`tool ${name} is not registered`);
-			const registered: {
-				execute(
-					id: string,
-					params: Record<string, unknown>,
-					signal?: AbortSignal,
-				): Promise<{
-					content: readonly {
-						type: string;
-						text?: string;
-						data?: string;
-						mimeType?: string;
-					}[];
-					isError?: boolean;
-				}>;
-			}[] = [];
 			const channel = runOptions?.channel ?? "test:1";
 			const session = {
 				kind: "agent",
@@ -660,44 +655,18 @@ export async function testPlugin(
 					throw new Error("test session cannot run tasks");
 				},
 			} satisfies SessionContext;
-			const factory = tool.session.snapshot().factory(session);
-			// SAFETY: defineTool's session factory only calls registerTool; the fake captures its definition.
-			factory?.({
-				registerTool: (definition: (typeof registered)[number]) => {
-					registered.push(definition);
-				},
-			} as unknown as ExtensionAPI);
-			const execute = registered[0]?.execute;
-			if (!execute)
+			const [registered] = await registeredTools(
+				tool.session.snapshot().factory(session),
+			);
+			if (!registered)
 				throw new PluginError(`tool ${name} did not register in the session`);
-			const result = await withReplyFiles(
+			const result = await callRegisteredTool(
+				registered,
+				args,
 				surfaces.of(channel)?.supportsFiles === true,
-				async () => {
-					const output = await execute("test-call", args);
-					for (const item of output.content)
-						if (item.type === "image" && item.data && item.mimeType)
-							images.push({
-								channel,
-								image: {
-									mimeType: item.mimeType,
-									data: new Uint8Array(Buffer.from(item.data, "base64")),
-								},
-							});
-					return {
-						ok: true,
-						text: output.content
-							.filter((item) => item.type === "text")
-							.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);
-			}
+			for (const image of result.images) images.push({ channel, image });
+			for (const file of result.files) files.push({ channel, file });
 			return result.text;
 		},
 		async stop() {

package/templates/official/codex-images/plugin.test.ts.tmpl

@@ -1,6 +1,6 @@
 import { expect, test } from "bun:test";
 import { PluginError } from "pi-roundtable";
-import { testPlugin } from "pi-roundtable/testing";
+import { recordingLogger, testPlugin } from "pi-roundtable/testing";
 import {
 	type CodexFetch,
 	codexImages,
@@ -116,3 +116,31 @@ test("codex-images refuses to start without an openai-codex login", async () =>
 	expect((failure as PluginError).message).toContain("openai-codex");
 	expect((failure as PluginError).message).toContain("Log in");
 });
+
+test("codex-images with onMissingLogin warn starts without a login and fails the drawing", async () => {
+	const plugin = createCodexImages({
+		onMissingLogin: "warn",
+		fetch: async () => stream(completed),
+	});
+	const harness = await testPlugin(plugin);
+	const failure = await plugin.providers?.images?.("a fox", []).then(
+		() => undefined,
+		(error: unknown) => error,
+	);
+	expect(failure).toBeInstanceOf(PluginError);
+	expect((failure as PluginError).message).toContain("openai-codex");
+	await harness.stop();
+});
+
+test("codex-images with onMissingLogin warn logs one warning at setup", async () => {
+	const { logger, lines } = recordingLogger();
+	const plugin = createCodexImages({ onMissingLogin: "warn" });
+	// SAFETY: setup reads only apiKey and logger.
+	await plugin.setup?.({ apiKey: async () => undefined, logger } as never);
+	expect(lines.map((line) => line.level)).toEqual(["warn"]);
+	expect(lines[0]?.message).toContain("openai-codex");
+	expect(lines[0]?.message).toContain(
+		"Drawing images fails until the login exists.",
+	);
+	expect(lines[0]?.message).not.toContain("plugin codex-images:");
+});

package/templates/official/codex-images/plugin.ts

@@ -31,6 +31,11 @@ export interface CodexImagesOptions {
 	fetch?: CodexFetch;
 	/** The model that routes the request; default `gpt-6-sol`. */
 	model?: string;
+	/**
+	 * What setup does when the openai-codex login is missing or unusable: "throw" (the default)
+	 * stops the host; "warn" logs a warning, and a drawing then fails with the same PluginError.
+	 */
+	onMissingLogin?: "throw" | "warn";
 }
 
 /** The ChatGPT account the login token belongs to, from the token's claims. */
@@ -197,7 +202,11 @@ const NO_LOGIN = `the host has no login for ${CODEX_PROVIDER}, the provider that
 
 /** The plugin, with its request function and model replaceable for a test. */
 export function createCodexImages(options: CodexImagesOptions = {}) {
-	const { fetch: fetchImpl = fetch, model = CODEX_MODEL } = options;
+	const {
+		fetch: fetchImpl = fetch,
+		model = CODEX_MODEL,
+		onMissingLogin = "throw",
+	} = options;
 	let apiKey: ((provider: string) => Promise<string | undefined>) | undefined;
 	// The login refreshes its token, so each image reads it again instead of keeping the first.
 	const token = async (): Promise<string> => {
@@ -214,7 +223,15 @@ export function createCodexImages(options: CodexImagesOptions = {}) {
 		},
 		async setup(context) {
 			apiKey = context.apiKey;
-			await token();
+			try {
+				await token();
+			} catch (error) {
+				if (onMissingLogin !== "warn" || !(error instanceof PluginError))
+					throw error;
+				context.logger.warn(
+					`${NO_LOGIN} Drawing images fails until the login exists.`,
+				);
+			}
 			return {};
 		},
 	});