pi-roundtable 0.16.0 → 0.17.1

package/src/core/testing/postgres.ts

@@ -0,0 +1,160 @@
+import { afterAll } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SQL } from "bun";
+import { adoptTestDatabase } from "./database.ts";
+
+export interface UsePostgresOptions {
+	/** Directories searched for initdb and postgres before PATH; default PG_BIN and the usual Homebrew and Debian paths. */
+	binDirs?: readonly string[];
+	/** Throw when initdb or postgres is not found; default false (the tests that need it skip or call requireDatabase). */
+	require?: boolean;
+}
+
+/** Where a PostgreSQL install usually keeps initdb and postgres, newest first. */
+const USUAL_DIRS = [
+	...[17, 16, 15, 14].map(
+		(major) => `/opt/homebrew/opt/postgresql@${major}/bin`,
+	),
+	...[17, 16, 15, 14].map((major) => `/usr/lib/postgresql/${major}/bin`),
+	"/usr/local/bin",
+	"/usr/bin",
+];
+
+const READY_TIMEOUT_MS = 20_000;
+const STOP_TIMEOUT_MS = 10_000;
+
+function binary(name: string, dirs: readonly string[]): string | undefined {
+	for (const dir of dirs) {
+		const path = join(dir, name);
+		if (existsSync(path)) return path;
+	}
+	return Bun.which(name) ?? undefined;
+}
+
+/** A TCP port nothing listens on, found by binding port 0 and letting it go. */
+async function freePort(): Promise<number> {
+	const probe = Bun.serve({
+		port: 0,
+		hostname: "127.0.0.1",
+		fetch: () => new Response(),
+	});
+	const port = probe.port ?? 0;
+	await probe.stop(true);
+	return port;
+}
+
+/** Waits until the server at `url` answers a query, or throws when it exited or the wait ran out. */
+async function untilReady(url: string, server: Bun.Subprocess): Promise<void> {
+	const deadline = Date.now() + READY_TIMEOUT_MS;
+	for (;;) {
+		if (server.exitCode !== null)
+			throw new Error(
+				`the test PostgreSQL exited with code ${server.exitCode} before it was ready`,
+			);
+		const sql = new SQL(url, { max: 1 });
+		try {
+			await sql`SELECT 1`;
+			await sql.close();
+			return;
+		} catch {
+			await sql.close().catch(() => undefined);
+			if (Date.now() > deadline)
+				throw new Error(
+					`the test PostgreSQL did not become ready in ${READY_TIMEOUT_MS / 1000} seconds`,
+				);
+			await Bun.sleep(100);
+		}
+	}
+}
+
+/**
+ * For a test preload: unless ROUNDTABLE_TEST_DATABASE_URL is set, starts a throwaway PostgreSQL on
+ * 127.0.0.1 (trust auth, fsync off, a temporary data directory), sets the variable and
+ * `testDatabaseUrl`, and stops and removes it after the run (bun's global afterAll, exit and signals).
+ */
+export async function usePostgresForTests(
+	options: UsePostgresOptions = {},
+): Promise<void> {
+	const given = process.env.ROUNDTABLE_TEST_DATABASE_URL;
+	if (given) {
+		adoptTestDatabase(given);
+		return;
+	}
+	const dirs = options.binDirs ?? [process.env.PG_BIN ?? "", ...USUAL_DIRS];
+	const initdb = binary("initdb", dirs.filter(Boolean));
+	const postgres = binary("postgres", dirs.filter(Boolean));
+	if (!initdb || !postgres) {
+		if (options.require)
+			throw new Error(
+				"this run needs PostgreSQL: install it so initdb and postgres are on PATH, set PG_BIN to its bin directory, or set ROUNDTABLE_TEST_DATABASE_URL to a throwaway database",
+			);
+		return;
+	}
+	const root = mkdtempSync(join(tmpdir(), "roundtable-test-pg-"));
+	const data = join(root, "data");
+	const init = spawnSync(
+		initdb,
+		["-D", data, "-U", "postgres", "--auth=trust", "-E", "UTF8", "--no-sync"],
+		{ encoding: "utf8" },
+	);
+	if (init.status !== 0) {
+		rmSync(root, { recursive: true, force: true });
+		throw new Error(`initdb failed: ${init.stderr}`);
+	}
+	const port = await freePort();
+	const server = Bun.spawn(
+		[
+			postgres,
+			"-D",
+			data,
+			"-p",
+			String(port),
+			"-k",
+			root,
+			"-c",
+			"listen_addresses=127.0.0.1",
+			"-c",
+			"fsync=off",
+		],
+		{ stdout: "ignore", stderr: "ignore" },
+	);
+	let stopped = false;
+	const stop = async () => {
+		if (stopped) return;
+		stopped = true;
+		// SIGINT is PostgreSQL's fast shutdown: sessions end and the server exits at once.
+		server.kill("SIGINT");
+		await Promise.race([server.exited, Bun.sleep(STOP_TIMEOUT_MS)]);
+		rmSync(root, { recursive: true, force: true });
+	};
+	// A global hook of the run: bun runs preload hooks once, after every test file.
+	afterAll(stop);
+	process.on("exit", () => {
+		if (stopped) return;
+		server.kill("SIGINT");
+		// A process that exits without the run's hooks leaves no data directory behind. The server
+		// writes while it shuts down, so removing it takes a few tries.
+		for (let attempt = 0; attempt < 100 && existsSync(root); attempt++) {
+			try {
+				rmSync(root, { recursive: true, force: true });
+			} catch {
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+			}
+		}
+	});
+	for (const signal of ["SIGINT", "SIGTERM"] as const)
+		process.on(signal, () => {
+			void stop().then(() => process.exit(1));
+		});
+	const url = `postgres://postgres@127.0.0.1:${port}/postgres`;
+	try {
+		await untilReady(url, server);
+	} catch (error) {
+		await stop();
+		throw error;
+	}
+	adoptTestDatabase(url);
+}

package/src/core/testing/run-tool.ts

@@ -0,0 +1,110 @@
+import type {
+	ExtensionAPI,
+	ExtensionFactory,
+} from "@earendil-works/pi-coding-agent";
+import type { ClientPart } from "../domain/client.ts";
+import type { ReplyFile } from "../domain/conversation.ts";
+import { PluginError } from "../errors.ts";
+import {
+	attachReplyFile,
+	hasReplyFileScope,
+	withReplyFiles,
+} from "../reply-files.ts";
+
+/** What a session registers of a tool: the call the model's tool call reaches. */
+export interface RegisteredTool {
+	name: string;
+	execute(
+		id: string,
+		params: Record<string, unknown>,
+		signal?: AbortSignal,
+	): Promise<{
+		content: readonly {
+			type: string;
+			text?: string;
+			data?: string;
+			mimeType?: string;
+		}[];
+		isError?: boolean;
+	}>;
+}
+
+/** What the model would get back from one tool call, and what the call attached beside the text. */
+export interface ToolCallResult {
+	text: string;
+	files: ReplyFile[];
+	images: ClientPart[];
+}
+
+/** 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, in order; every other registration (handlers, commands, events) is accepted and ignored. */
+export async function registeredTools(
+	factory: ExtensionFactory | null | undefined,
+): Promise<RegisteredTool[]> {
+	const tools: RegisteredTool[] = [];
+	if (!factory) return tools;
+	// SAFETY: a session factory only registers tools, handlers and commands; the fake records the tools and ignores the rest.
+	const api = new Proxy(
+		{},
+		{
+			get: (_target, key) =>
+				key === "registerTool"
+					? (definition: RegisteredTool) => tools.push(definition)
+					: ignored(),
+		},
+	) as unknown as ExtensionAPI;
+	await factory(api);
+	return tools;
+}
+
+/**
+ * Runs the call as a turn on a surface that takes files or not runs it: the text, the files it
+ * attached and the images it returned. A file is also queued for the enclosing real turn when a
+ * fake runtime runs the call inside one. A tool that throws throws here; a refusal (an `isError` result) comes back as its text.
+ */
+export async function callRegisteredTool(
+	tool: RegisteredTool,
+	args: Record<string, unknown>,
+	supportsFiles: boolean,
+): Promise<ToolCallResult> {
+	const images: ClientPart[] = [];
+	const result = await withReplyFiles(supportsFiles, async () => {
+		const output = await tool.execute("test-call", args);
+		for (const item of output.content)
+			if (item.type === "image" && item.data && item.mimeType)
+				images.push({
+					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;
+	const files = result.files ?? [];
+	// When a tool is run by a fake runtime, forward into the enclosing real turn.
+	if (hasReplyFileScope()) for (const file of files) attachReplyFile(file);
+	return { text: result.text, files, images };
+}
+
+/** The registered tool called `name`, or the PluginError a test reads. */
+export function toolNamed(
+	tools: readonly RegisteredTool[],
+	name: string,
+): RegisteredTool {
+	const found = tools.find((tool) => tool.name === name);
+	if (!found) throw new PluginError(`tool ${name} is not registered`);
+	return found;
+}

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 {};
 		},
 	});