pi-roundtable 0.2.1 → 0.4.0

package/src/core/modules/delegation/web-research-worker.ts

@@ -6,6 +6,7 @@ import {
 	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
+import { PluginError } from "../../errors.ts";
 import {
 	formatModelRef,
 	type ModelRef,
@@ -20,6 +21,18 @@ const WEB_TOOLS = ["web_search", "fetch_content", "get_search_content"];
 const WORKER_PROMPT =
 	"You are a research worker. Another agent handed you the task below and will pass your report on. Do it with web search and page reading, preferring primary sources. Report in the task's language, self-contained, with a source link for each claim, and say what you could not verify.";
 
+/** The folder of `pi-web-access`, a peer dependency the host installs, or a PluginError that says how. */
+function webAccessDir(): string {
+	try {
+		return packageDir("pi-web-access");
+	} catch (error) {
+		throw new PluginError(
+			"the delegation worker loads pi-web-access, which this project does not have installed. It is a peer dependency of pi-roundtable: run `bun add pi-web-access@0.35.0` (or your own build of it, which the worker then uses too).",
+			{ cause: error },
+		);
+	}
+}
+
 export interface WebResearchWorkerOptions {
 	/** Shared with the rest of the host, so the Codex login refreshes in one place. */
 	modelRuntime: ModelRuntime;
@@ -36,7 +49,7 @@ export class WebResearchWorker {
 
 	constructor(options: WebResearchWorkerOptions) {
 		this.#options = options;
-		this.#webAccessPath = packageDir("pi-web-access");
+		this.#webAccessPath = webAccessDir();
 		mkdirSync(options.workDir, { recursive: true });
 	}
 

package/src/core/plugin.ts

@@ -268,6 +268,12 @@ export interface PluginContext {
 	providers: ResolvedProviders;
 	/** Every plugin's dashboard lines, in contribution order; throws NotLinkedError during setup. */
 	dashboard(): readonly string[];
+	/**
+	 * The credential the host's model login holds for a provider, such as `openai-codex`: the same
+	 * login the agents use. Resolves to `undefined` when the host has none for that provider, and
+	 * never throws for that. The value is a secret: keep it out of logs and error messages.
+	 */
+	apiKey(provider: string): Promise<string | undefined>;
 }
 
 export interface RoundtablePlugin {
@@ -281,6 +287,14 @@ export interface RoundtablePlugin {
 	 * list before any setup, and refuses the plugin when setup returns without providing one.
 	 */
 	provides?: readonly ServiceKey<unknown>[];
+	/**
+	 * The services this plugin's setup reads with `get`, so the host can check them before any
+	 * setup and any migration: a key no registered plugin provides, or one provided by a plugin
+	 * registered after this one, is a PluginError that names both plugins and the fix. A service
+	 * read only after startup, from a callback, is `services.lazy` instead, which does not depend
+	 * on order. Leave out a service read with `find`, since that one may be absent.
+	 */
+	requires?: readonly ServiceKey<unknown>[];
 	/**
 	 * Services this plugin replaces. The host drops the plugin that provides them and sets this one
 	 * up where it stood, so it may read what the plugins before that place provide and nothing

package/src/core/registry/contributions.ts

@@ -385,6 +385,7 @@ export async function collectContributions(
 		registry.prompt.push(...prompt);
 		registry.requiredTools.push(...requiredTools);
 	}
+	services.settle();
 	return registry;
 }
 

package/src/core/registry/services.ts

@@ -1,5 +1,5 @@
 import type { ServiceKey, Services } from "../contract/services.ts";
-import { PluginError } from "../errors.ts";
+import { NotLinkedError, PluginError } from "../errors.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
 
 /** The host's words for reading a service no plugin declares; `testPlugin` says how to give one instead. */
@@ -29,6 +29,22 @@ function declaredBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
 	return provides;
 }
 
+/** The services a plugin requires, checked to be a list of keys; empty when it requires none. */
+function requiredBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
+	const { requires } = plugin;
+	if (requires === undefined) return [];
+	if (!Array.isArray(requires))
+		throw new PluginError(
+			`plugin ${plugin.name}: requires must be a list of service keys made with serviceKey().`,
+		);
+	for (const key of requires)
+		if (typeof key?.id !== "string" || key.id === "")
+			throw new PluginError(
+				`plugin ${plugin.name}: requires has an entry that is not a service key; make each with serviceKey("<id>").`,
+			);
+	return requires;
+}
+
 /** The services a plugin replaces, checked to be a list of keys; empty when it replaces none. */
 function replacedBy(plugin: RoundtablePlugin): readonly ServiceKey<unknown>[] {
 	const { replaces } = plugin;
@@ -127,10 +143,16 @@ export class ServiceRegistry {
 	#setting: RoundtablePlugin | undefined;
 	/** The plugins that have read a service, such as one that adds its commands through it. */
 	readonly #readers = new Set<RoundtablePlugin>();
+	readonly #plugins: readonly RoundtablePlugin[];
+	/** What each plugin asked `lazy` for, to refuse a key nobody provides once every plugin is set up. */
+	readonly #lazy: { plugin: RoundtablePlugin; key: ServiceKey<unknown> }[] = [];
+	/** Whether every plugin is set up, from which a `lazy` reader returns its service. */
+	#settled = false;
 
 	/** `advice` says how to get a service no plugin declares; the host's is to register one that does. */
 	constructor(plugins: readonly RoundtablePlugin[], advice = HOST_ADVICE) {
 		this.#advice = advice;
+		this.#plugins = plugins;
 		for (const plugin of plugins)
 			for (const key of declaredBy(plugin)) {
 				const other = this.#declaredBy.get(key.id);
@@ -147,6 +169,45 @@ export class ServiceRegistry {
 		this.#values.set(key.id, value);
 	}
 
+	/**
+	 * Refuses a plugin whose `requires` names a service no registered plugin or test provides, or
+	 * one a plugin registered after it provides. It runs before any migration or setup, so a wrong
+	 * order fails at the start with both plugins named.
+	 */
+	checkRequires(): void {
+		this.#plugins.forEach((plugin, index) => {
+			for (const key of requiredBy(plugin)) {
+				if (this.#values.has(key.id)) continue;
+				const provider = this.#declaredBy.get(key.id);
+				if (!provider)
+					throw new PluginError(
+						`plugin ${plugin.name}: requires service ${key.id}, which no registered plugin provides. ${key.absent ?? this.#advice}`,
+					);
+				if (provider === plugin)
+					throw new PluginError(
+						`plugin ${plugin.name}: requires service ${key.id}, which it provides itself. A plugin cannot require what it provides.`,
+					);
+				if (this.#plugins.indexOf(provider) > index)
+					throw new PluginError(
+						`plugin ${plugin.name}: requires service ${key.id}, which plugin ${provider.name} provides after it. Register plugin ${provider.name} before plugin ${plugin.name}, or read the service with services.lazy(KEY) from a callback that runs after startup.`,
+					);
+			}
+		});
+	}
+
+	/**
+	 * Called once every plugin is set up: `lazy` readers start answering, and a key a plugin asked
+	 * for that nobody provides is refused with the plugin named.
+	 */
+	settle(): void {
+		for (const { plugin, key } of this.#lazy)
+			if (!this.#values.has(key.id))
+				throw new PluginError(
+					`plugin ${plugin.name}: services.lazy reads service ${key.id}, which no registered plugin provides. ${key.absent ?? this.#advice}`,
+				);
+		this.#settled = true;
+	}
+
 	/** The service, for the host's own reads; throws like a plugin's `get`. */
 	get<T>(key: ServiceKey<T>): T {
 		return this.#read(key, undefined, true) as T;
@@ -185,6 +246,17 @@ export class ServiceRegistry {
 				this.#readers.add(plugin);
 				return this.#read(key, plugin, false);
 			},
+			lazy: <T>(key: ServiceKey<T>) => {
+				this.#readers.add(plugin);
+				this.#lazy.push({ plugin, key });
+				return () => {
+					if (!this.#settled)
+						throw new NotLinkedError(
+							`service ${key.id} is read through lazy() once every plugin is set up. Call it from a service's start or from a handler, not during setup.`,
+						);
+					return this.#values.get(key.id) as T;
+				};
+			},
 			provide: (key, value) => {
 				if (this.#setting !== plugin)
 					throw new PluginError(

package/src/core/runtime/session-factory.ts

@@ -77,7 +77,7 @@ export class SessionFactory {
 			const linked = this.#options.sessions();
 			this.#linked = {
 				...linked,
-				extensionPaths: linked.piPackages.map(packageDir),
+				extensionPaths: linked.piPackages.map((name) => packageDir(name)),
 			};
 		}
 		return this.#linked;

package/src/core/shared/package-dir.ts

@@ -1,9 +1,12 @@
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
 
-const require = createRequire(import.meta.url);
-
-/** The installed package's folder, as Pi's `additionalExtensionPaths` takes it. */
-export function packageDir(name: string): string {
-	return dirname(require.resolve(`${name}/package.json`));
+/**
+ * The installed package's folder, as Pi's `additionalExtensionPaths` takes it. The package is
+ * looked up from `from`, which is `import.meta.url` of the module that asks, so a host finds its
+ * own dependencies even when `pi-roundtable` is linked or installed apart from them; without it
+ * the lookup starts at the core's own files.
+ */
+export function packageDir(name: string, from: string | URL = import.meta.url) {
+	return dirname(createRequire(from).resolve(`${name}/package.json`));
 }

package/src/core/shared/unix-server.ts

@@ -0,0 +1,26 @@
+import { rmSync } from "node:fs";
+import type { Server } from "bun";
+
+/**
+ * Serves HTTP on a unix socket without Bun's 10-second idle timeout, which would cut long
+ * turns and quiet model streams. Bun 1.4.2 honors `idleTimeout` on unix sockets, but its
+ * types reject the option there, hence the cast. A stale socket file is removed first.
+ * `error` answers a failure raised outside the fetch handler; without it Bun's own page is sent.
+ */
+export function serveUnix(
+	socketPath: string,
+	fetch: (request: Request) => Response | Promise<Response>,
+	options: { error?: (error: Error) => Response | Promise<Response> } = {},
+): Server<undefined> {
+	rmSync(socketPath, { force: true });
+	const serveOptions = {
+		unix: socketPath,
+		idleTimeout: 0,
+		fetch,
+		...(options.error ? { error: options.error } : {}),
+	};
+	// SAFETY: these are Bun's unix-socket options; only `idleTimeout` is missing from its types.
+	return Bun.serve(
+		serveOptions as unknown as Parameters<typeof Bun.serve>[0],
+	) as Server<undefined>;
+}

package/src/core/testing/partial.ts

@@ -0,0 +1,21 @@
+/** Members a probe may ask of any object: a test's stand-in is not refused for them. */
+const PROBED = new Set(["then", "toJSON", "asymmetricMatch"]);
+
+/**
+ * A stand-in for a port the code under test takes, made of only the members the test gives.
+ * Reading any other member throws an error that names it, so a test learns at once which member
+ * the code reaches for, instead of meeting `undefined is not a function` or a hidden cast.
+ * `partial<AgentTeam>({ announce })` is an `AgentTeam` to the type checker.
+ */
+export function partial<T extends object>(given: Partial<T>): T {
+	// SAFETY: the stand-in answers only the members given; any other read throws before it is used.
+	return new Proxy(given, {
+		get(target, member, receiver) {
+			if (member in target || typeof member === "symbol" || PROBED.has(member))
+				return Reflect.get(target, member, receiver);
+			throw new Error(
+				`partial() was given no "${member}". Give it where the stand-in is made: partial({ ${member}: ... }).`,
+			);
+		},
+	}) as T;
+}

package/src/core/testing/recording-logger.ts

@@ -0,0 +1,44 @@
+import type { Logger } from "../log.ts";
+
+/** One line a recording logger kept. */
+export interface RecordedLog {
+	level: "debug" | "info" | "warn" | "error" | "fatal";
+	/** The fields of the call, with those of every `child` the logger came from. */
+	fields: Record<string, unknown>;
+	message: string;
+}
+
+/** A logger that keeps what it is asked to write, and the lines it kept. */
+export interface RecordingLogger {
+	readonly logger: Logger;
+	/** Every line written through the logger or a child of it, in order. */
+	readonly lines: RecordedLog[];
+}
+
+/**
+ * A logger for a test that checks what the code logs: it writes nowhere, and `lines` holds each
+ * call with its level, fields (a child's included), and message.
+ */
+export function recordingLogger(): RecordingLogger {
+	const lines: RecordedLog[] = [];
+	const make = (bound: Record<string, unknown>): Logger => {
+		const write =
+			(level: RecordedLog["level"]) =>
+			(first: object | string, message?: string): void => {
+				lines.push(
+					typeof first === "string"
+						? { level, fields: { ...bound }, message: first }
+						: { level, fields: { ...bound, ...first }, message: message ?? "" },
+				);
+			};
+		return {
+			debug: write("debug"),
+			info: write("info"),
+			warn: write("warn"),
+			error: write("error"),
+			fatal: write("fatal"),
+			child: (fields) => make({ ...bound, ...fields }),
+		};
+	};
+	return { logger: make({}), lines };
+}

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

@@ -38,6 +38,11 @@ export interface TestHostOptions {
 	plugins?: readonly RoundtablePlugin[];
 	/** The runtime every turn runs on; by default one that answers "" and builds no Pi session. */
 	runtime?: AgentRuntime;
+	/**
+	 * The credentials `context.apiKey` returns, by provider name; a provider not listed reads as
+	 * having none, whatever login the machine holds.
+	 */
+	apiKeys?: Readonly<Record<string, string>>;
 	/** What the stand-in Discord hands out. */
 	discord?: Partial<Pick<DiscordConnection, "agentChannels" | "ownerChannel">>;
 }
@@ -210,7 +215,15 @@ export async function testHost(
 		],
 	};
 	const defined = await defineRoundtable(config, { logger: silentLogger() });
-	const roundtable = new Roundtable(defined.options, defined.plugins);
+	const apiKeys = options.apiKeys ?? {};
+	const roundtable = new Roundtable(
+		{
+			...defined.options,
+			apiKey: async (provider) =>
+				Object.hasOwn(apiKeys, provider) ? apiKeys[provider] : undefined,
+		},
+		defined.plugins,
+	);
 	await roundtable.run();
 	if (!captured) throw new Error("the probe was not set up");
 	const context = captured;

package/src/discord/index.ts

@@ -1,5 +1,5 @@
 // The Discord entry: everything that names a discord.js type, apart from the main and kit entries.
-// Unstable before 1.0; not covered by semver.
+// Versioned like the main entry: a breaking change comes in a minor release before 1.0 and is listed in the changelog.
 
 export type { DiscordServices } from "../core/builtin/discord.ts";
 export { DISCORD } from "../core/builtin/discord.ts";

package/src/kit/channels.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { discordKey } from "../core/agents/team-keys.ts";
 

package/src/kit/domain.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { AgentError } from "../core/domain/errors.ts";
 export type {

package/src/kit/holds.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // The chain a host links from every plugin's hold rules, to test a rule set as the host runs it.
 
 export { holdChain } from "../core/holds.ts";

package/src/kit/index.ts

@@ -1,4 +1,4 @@
-// Unstable before 1.0; not covered by semver. Helpers for owner commands, claims, and naming existing core parts.
+// Helpers for owner commands, claims, and naming existing core parts; versioned like the main entry.
 
 export type { ChannelQueue } from "./channels.ts";
 export {
@@ -62,6 +62,7 @@ export {
 	thinkingLine,
 	zonedStamp,
 } from "./presentation.ts";
+export { packageDir, serveUnix } from "./process.ts";
 export {
 	SHELL_TOOLS,
 	shellHoldRule,

package/src/kit/judging.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export type {
 	EffortBrief,

package/src/kit/memory.ts

@@ -1,3 +1,3 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { searchTerms } from "../core/modules/memory/owner-memory-store.ts";

package/src/kit/mirror.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // Mirror a built-in tool in a worker that cannot reach the host: the specs and the dispatcher.
 
 export type { ScheduleToolContext } from "../core/modules/schedules/schedule-tools.ts";

package/src/kit/presentation.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export { headline } from "../core/presentation/headline.ts";
 export { quietLinks } from "../core/presentation/quiet-links.ts";

package/src/kit/process.ts

@@ -0,0 +1,5 @@
+// Plugin helpers, versioned like the main entry; see the plugin guide.
+// Running a worker process of your own: where an installed package lives, and a unix-socket HTTP server.
+
+export { packageDir } from "../core/shared/package-dir.ts";
+export { serveUnix } from "../core/shared/unix-server.ts";

package/src/kit/shell.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // The host-shell tools and the hold rule that keeps risky commands behind the owner's approval.
 
 export {

package/src/kit/skills.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // Skills and repositories: the names a repository shelf accepts, and the tool that lists skills.
 
 export { checkRepoName } from "../core/modules/skills/repo-name.ts";

package/src/kit/support.ts

@@ -1,4 +1,4 @@
-// Supporting data types for the unstable service and helper contracts.
+// Supporting data types for the service and helper contracts.
 
 export type {
 	AgentCategory,

package/src/kit/threads.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export type {
 	DispatchThread,

package/src/kit/tools.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 
 export type {
 	TextToolDef,

package/src/kit/worker.ts

@@ -1,4 +1,4 @@
-// Unstable plugin helpers; see the plugin guide.
+// Plugin helpers, versioned like the main entry; see the plugin guide.
 // Running a Pi session of your own: MCP servers for it, its work timeout, its held-action cards.
 
 export {

package/src/testing.ts

@@ -63,7 +63,6 @@ import { type ToolTierTable, toolTiers } from "./core/tool-tiers.ts";
 // Fixtures for plugin tests.
 
 export { silentLogger } from "./core/log.ts";
-
 export type { TestStore } from "./core/testing/database.ts";
 export {
 	describeDb,
@@ -74,8 +73,13 @@ export {
 export { eagerText, useEagerCatalog } from "./core/testing/eager-catalog.ts";
 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 {
+	RecordedLog,
+	RecordingLogger,
+} from "./core/testing/recording-logger.ts";
+export { recordingLogger } from "./core/testing/recording-logger.ts";
 export type { TestHost, TestHostOptions } from "./core/testing/test-host.ts";
 export { testHost } from "./core/testing/test-host.ts";
 export type { FakeThreadHost } from "./core/testing/thread-host.ts";
@@ -170,6 +174,11 @@ export interface TestPluginOptions {
 	conversations?: Partial<ConversationPort>;
 	/** Replaces `context.turns`, which by default runs turns over the runtime and the surfaces. */
 	turns?: ConversationTurns;
+	/**
+	 * The credentials `context.apiKey` returns, by provider name; a provider not listed reads as
+	 * having none, as on a host that is not logged in to it.
+	 */
+	apiKeys?: Readonly<Record<string, string>>;
 	/** How long the router holds a bare forward for the message that follows it; the host option `conversations.forwardJoinMs`. */
 	forwardJoinMs?: number;
 }
@@ -393,6 +402,7 @@ export async function testPlugin(
 				logger,
 			}),
 		);
+	services.checkRequires();
 	const context: Omit<PluginContext, "services"> = {
 		logger,
 		env,
@@ -409,6 +419,10 @@ export async function testPlugin(
 		},
 		providers,
 		dashboard: () => (linked ? registry.dashboard : unlinked("dashboard")),
+		apiKey: async (provider) =>
+			Object.hasOwn(options.apiKeys ?? {}, provider)
+				? options.apiKeys?.[provider]
+				: undefined,
 	};
 	const registry = await collectContributions(
 		[plugin],

package/templates/agents.ts

@@ -1,5 +1,8 @@
 import type { AgentSeed } from "pi-roundtable";
 
+// Ids come from .env, which Bun loads on its own.
+const env = (name: string): string => process.env[name] ?? "";
+
 // The first team. An agent that is already stored is never overwritten, so edit agents in Discord afterwards.
 export const agents: AgentSeed[] = [
 	{
@@ -8,5 +11,7 @@ export const agents: AgentSeed[] = [
 		prompt:
 			"You are Guide, a friendly assistant. Answer briefly and ask when a request is unclear.",
 		avatarPrompt: "A friendly lighthouse keeper with a warm lantern",
+		// The agent in the entry channel is the coordinator: it answers there and can create the others.
+		channelId: env("DISCORD_ENTRY_CHANNEL_ID"),
 	},
 ];

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

@@ -0,0 +1,118 @@
+import { expect, test } from "bun:test";
+import { PluginError } from "pi-roundtable";
+import { testPlugin } from "pi-roundtable/testing";
+import {
+	type CodexFetch,
+	codexImages,
+	createCodexImages,
+	ImageNotGeneratedError,
+} from "./codex-images.ts";
+
+/** A login token shaped like the real one: a JWT whose claims name the ChatGPT account. */
+function token(account: string): string {
+	const claims = {
+		"https://api.openai.com/auth": { chatgpt_account_id: account },
+	};
+	return `header.${Buffer.from(JSON.stringify(claims)).toString("base64url")}.signature`;
+}
+
+const PNG = Uint8Array.from([0x89, 0x50, 0x4e, 0x47]);
+
+/** A server-sent event stream of the given events. */
+function stream(...events: unknown[]): Response {
+	const text = events
+		.map((event) => `data: ${JSON.stringify(event)}\n\n`)
+		.join("");
+	return new Response(text, {
+		headers: { "content-type": "text/event-stream" },
+	});
+}
+
+const drawn = (result: string, status = "completed") => ({
+	type: "response.output_item.done",
+	item: { type: "image_generation_call", status, result },
+});
+
+const completed = { type: "response.completed", response: { output: [] } };
+
+/** The plugin over a fake network that answers every request with `answer`, recording the requests. */
+function over(answer: () => Response) {
+	const requests: { url: string; init: RequestInit }[] = [];
+	const fetch: CodexFetch = async (url, init) => {
+		requests.push({ url, init });
+		return answer();
+	};
+	return { plugin: createCodexImages({ fetch }), requests };
+}
+
+test("codex-images fills the images slot with the image Codex returns", async () => {
+	const secret = token("acct-1");
+	const { plugin, requests } = over(() =>
+		stream(drawn(Buffer.from(PNG).toString("base64")), completed),
+	);
+	const harness = await testPlugin(plugin, {
+		apiKeys: { "openai-codex": secret },
+	});
+	const image = await plugin.providers?.images?.("a fox", [
+		{ data: "AAAA", mimeType: "image/png" },
+	]);
+	expect([...(image ?? [])]).toEqual([...PNG]);
+	const [request] = requests;
+	expect(request?.url).toBe("https://chatgpt.com/backend-api/codex/responses");
+	const headers = request?.init.headers as Record<string, string>;
+	expect(headers.authorization).toBe(`Bearer ${secret}`);
+	expect(headers["chatgpt-account-id"]).toBe("acct-1");
+	const body = JSON.parse(String(request?.init.body));
+	expect(body.tools).toEqual([
+		{ type: "image_generation", output_format: "png" },
+	]);
+	expect(body.input[0].content).toEqual([
+		{ type: "input_text", text: "a fox" },
+		{ type: "input_image", image_url: "data:image/png;base64,AAAA" },
+	]);
+	await harness.stop();
+});
+
+test("codex-images says so when Codex runs the tool and returns no image", async () => {
+	const refused = over(() => stream(drawn("", "failed"), completed));
+	const harness = await testPlugin(refused.plugin, {
+		apiKeys: { "openai-codex": token("acct-1") },
+	});
+	await expect(refused.plugin.providers?.images?.("a fox", [])).rejects.toThrow(
+		ImageNotGeneratedError,
+	);
+	await harness.stop();
+	const silent = over(() => stream(completed));
+	const quiet = await testPlugin(silent.plugin, {
+		apiKeys: { "openai-codex": token("acct-1") },
+	});
+	await expect(silent.plugin.providers?.images?.("a fox", [])).rejects.toThrow(
+		"Codex answered without an image",
+	);
+	await quiet.stop();
+});
+
+test("codex-images reports an HTTP error with its status, and never the token", async () => {
+	const secret = token("acct-1");
+	const { plugin } = over(() => new Response("rate limited", { status: 429 }));
+	const harness = await testPlugin(plugin, {
+		apiKeys: { "openai-codex": secret },
+	});
+	const failure = await plugin.providers?.images?.("a fox", []).then(
+		() => undefined,
+		(error: Error) => error,
+	);
+	expect(failure?.message).toBe("Codex answered 429: rate limited");
+	expect(failure?.message).not.toContain(secret);
+	await harness.stop();
+});
+
+test("codex-images refuses to start without an openai-codex login", async () => {
+	const failure = await testPlugin(codexImages).then(
+		() => undefined,
+		(error: unknown) => error,
+	);
+	expect(failure).toBeInstanceOf(PluginError);
+	expect((failure as PluginError).message).toContain("openai-codex");
+	expect((failure as PluginError).message).toContain("Log in");
+});