pi-roundtable 0.17.3 → 0.19.0

package/src/kit/jev-judge.ts

@@ -0,0 +1,153 @@
+// A Judge over Jev's hosted service, built on pi-jev-compaction's client.
+
+import { JevClient, type JevQuestions } from "pi-jev-compaction";
+import type {
+	ChoiceAnswer,
+	ChoiceQuestion,
+	Judge,
+	ScoreQuestion,
+	YesNoQuestion,
+} from "../core/contract/providers.ts";
+import { JudgeError } from "../core/errors.ts";
+
+/** The service's name for the yes-or-no question and for its answer's probability. */
+const WIRE_YES_NO = "noul";
+type JevQuestion = JevQuestions[string];
+const DEFAULT_TIMEOUT_MS = 20_000;
+
+export interface JevJudgeOptions {
+	/** The service's API key. It is required: an empty one is refused, not looked up in the environment. */
+	apiKey: string;
+	/** The service's model; default pi-jev-compaction's. */
+	model?: string;
+	/** The service's endpoint; default pi-jev-compaction's. */
+	baseUrl?: string;
+	/** How long one question may take, the read of the answer included; default 20,000. */
+	timeoutMs?: number;
+	/** The request function; default the global `fetch`. */
+	fetch?: typeof fetch;
+}
+
+// pi-lens-ignore: no-unknown-parameters — a type guard over parsed JSON
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+// pi-lens-ignore: no-unknown-parameters — a type guard over parsed JSON
+const isProbability = (value: unknown): value is number =>
+	typeof value === "number" && value >= 0 && value <= 1;
+
+/**
+ * A `Judge` that asks Jev. Each question is one request with its own time limit of `timeoutMs`,
+ * which also covers reading the answer. Every failure throws a `JudgeError`: a missing answer,
+ * a probability outside 0 to 1, a choice that is not one of the listed options, a failed request,
+ * and a limit that ran out. An empty `apiKey` is refused when the judge is made.
+ */
+export function jevJudge(options: JevJudgeOptions): Judge {
+	const apiKey = options.apiKey.trim();
+	if (!apiKey)
+		throw new JudgeError(
+			"jevJudge needs an apiKey; an empty one would fall back to the environment's key",
+		);
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+	async function ask(
+		state: Record<string, unknown>,
+		questions: JevQuestions,
+	): Promise<Record<string, unknown>> {
+		const signal = AbortSignal.timeout(timeoutMs);
+		const client = new JevClient({
+			apiKey,
+			model: options.model,
+			baseUrl: options.baseUrl,
+			fetch: options.fetch,
+			signal,
+		});
+		try {
+			return (await client.ask(state, questions)).answers;
+		} catch (error) {
+			if (error instanceof JudgeError) throw error;
+			if (signal.aborted)
+				throw new JudgeError(`Jev did not answer within ${timeoutMs} ms`, {
+					cause: error,
+				});
+			const message = error instanceof Error ? error.message : String(error);
+			throw new JudgeError(
+				/^Jev/.test(message) ? message : `Jev request failed: ${message}`,
+				{ cause: error },
+			);
+		}
+	}
+
+	const malformed = (name: string, detail = "") =>
+		new JudgeError(`Jev's answer for ${name} is malformed${detail}`);
+
+	return {
+		async askYesNo(
+			state: Record<string, unknown>,
+			questions: Record<string, YesNoQuestion>,
+		): Promise<Record<string, number>> {
+			const names = Object.keys(questions);
+			if (names.length === 0) return {};
+			const answers = await ask(
+				state,
+				Object.fromEntries(
+					names.map((name) => {
+						const { type: _type, ...question } = questions[
+							name
+						] as YesNoQuestion;
+						return [name, { ...question, type: WIRE_YES_NO } as JevQuestion];
+					}),
+				),
+			);
+			// pi-lens-ignore: no-known-value-widening — filled per question name below
+			const result: Record<string, number> = {};
+			for (const name of names) {
+				const answer = answers[name];
+				const probability = isRecord(answer) ? answer[WIRE_YES_NO] : undefined;
+				if (!isProbability(probability)) throw malformed(name);
+				result[name] = probability;
+			}
+			return result;
+		},
+
+		async askChoice(
+			state: Record<string, unknown>,
+			name: string,
+			question: ChoiceQuestion,
+		): Promise<ChoiceAnswer> {
+			const answer = (await ask(state, { [name]: question }))[name];
+			if (
+				!isRecord(answer) ||
+				typeof answer.choice !== "string" ||
+				!isProbability(answer.confidence)
+			)
+				throw malformed(name);
+			if (!Object.hasOwn(question.criteria, answer.choice))
+				throw new JudgeError(
+					`Jev chose ${answer.choice}, which is not an option of ${name}`,
+				);
+			return { choice: answer.choice, confidence: answer.confidence };
+		},
+
+		async askScore(
+			state: Record<string, unknown>,
+			name: string,
+			question: ScoreQuestion,
+		): Promise<number[]> {
+			if (question.criteria.length === 0) return [];
+			const answer = (
+				await ask(state, {
+					[name]: { ...question, criteria: [...question.criteria] },
+				})
+			)[name];
+			const probabilities = isRecord(answer) ? answer.probabilities : undefined;
+			if (!isRecord(probabilities)) throw malformed(name);
+			return question.criteria.map((_, index) => {
+				const value = probabilities[String(index)];
+				if (!isProbability(value))
+					throw malformed(name, `: no probability for criterion ${index}`);
+				return value;
+			});
+		},
+	};
+}

package/src/kit/ops-alerts.ts

@@ -0,0 +1,9 @@
+// Plugin helpers, versioned like the main entry; see the plugin guide.
+// Short alerts for the people who run a host, held to a window so a fault cannot flood them.
+
+export type {
+	OpsAlertKind,
+	OpsAlertsOptions,
+	OpsRaiseOptions,
+} from "../core/ops/ops-alerts.ts";
+export { OpsAlerts } from "../core/ops/ops-alerts.ts";

package/src/testing.ts

@@ -29,6 +29,7 @@ import {
 	commandGuard,
 	ownerRootCommand,
 } from "./core/discord/owner-command.ts";
+import type { DiscordPoster } from "./core/discord/poster/poster.ts";
 import type { ClientPart, ClientPort } from "./core/domain/client.ts";
 import type {
 	PendingConfirmation,
@@ -76,6 +77,7 @@ import {
 } from "./core/services.ts";
 import type { ChannelKey, SessionContext } from "./core/sessions.ts";
 import { type Speaker, THE_SPEAKER } from "./core/speakers.ts";
+import { fakeDiscordPoster } from "./core/testing/fake-poster.ts";
 import { mapIdentity } from "./core/testing/map-identity.ts";
 import {
 	callRegisteredTool,
@@ -95,6 +97,12 @@ export {
 	testDatabaseUrl,
 } from "./core/testing/database.ts";
 export { eagerText, useEagerCatalog } from "./core/testing/eager-catalog.ts";
+export type {
+	FakeDiscordPoster,
+	FakePosterChannel,
+	FakePosterMessage,
+} from "./core/testing/fake-poster.ts";
+export { fakeDiscordPoster } from "./core/testing/fake-poster.ts";
 export type { TestLocale } from "./core/testing/locale.ts";
 export { useTestLocale } from "./core/testing/locale.ts";
 export { OWNER_SPEAKER } from "./core/testing/owner.ts";
@@ -156,6 +164,8 @@ export interface FakeDiscord {
 	readonly service: ServicePair;
 	/** What `DISCORD.commands` is to the plugin: the real registrar, which refuses what the Discord plugin refuses. */
 	readonly commands: CommandRegistrar;
+	/** What `DISCORD.poster` is: the one the test gave, else a `fakeDiscordPoster()`. */
+	readonly poster: DiscordPoster;
 	/** What `DISCORD.guard` is: the owner, `owner` unless the test gave another id, serving the root command. */
 	readonly guard: CommandGuard;
 	/** Every contribution the plugin added, in the order it added them. */
@@ -169,13 +179,14 @@ export interface FakeDiscord {
  * plugin's `commands.add` calls are recorded, and `compose()` shows the tree Discord would get.
  * `rootCommand` is the root command's name, `roundtable` by default. `channelContext` is what
  * `DISCORD.channelContext` answers, by default no context, as on a host with it off. Only
- * `commands`, `guard`, and `channelContext` are given; reading another member throws.
+ * `commands`, `guard`, `poster`, and `channelContext` are given; reading another member throws.
  */
 export function fakeDiscord(
 	options: {
 		ownerId?: string;
 		rootCommand?: string;
 		channelContext?: DiscordServices["channelContext"];
+		poster?: DiscordPoster;
 	} = {},
 ): FakeDiscord {
 	const collection = new CommandCollection();
@@ -185,12 +196,15 @@ export function fakeDiscord(
 		root: rootCommand,
 		logger: silentLogger(),
 	});
+	const poster = options.poster ?? fakeDiscordPoster();
 	return {
 		service: servicePair(DISCORD, {
 			commands: collection.registrar,
 			guard,
+			poster,
 			channelContext: options.channelContext ?? (async () => undefined),
 		}),
+		poster,
 		commands: collection.registrar,
 		guard,
 		added: () => collection.added(),

package/templates/adapters/web/package.json.tmpl

@@ -16,11 +16,11 @@
 		"pi-roundtable": "__VERSION__",
 		"pi-roundtable-webchat": "__VERSION__",
 		"pi-self-compact": "0.2.0",
-		"typebox": "1.3.34"
+		"typebox": "1.3.37"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
-		"@types/bun": "1.4.2",
+		"@types/bun": "1.4.3",
 		"typescript": "7.0.2"
 	}
 }

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

@@ -107,6 +107,37 @@ test("codex-images reports an HTTP error with its status, and never the token",
 	await harness.stop();
 });
 
+test("codex-images aborts a drawing with the turn that asked for it", async () => {
+	const signals: AbortSignal[] = [];
+	const plugin = createCodexImages({
+		fetch: (_url, init) => {
+			const signal = init.signal as AbortSignal;
+			signals.push(signal);
+			return new Promise((_resolve, reject) => {
+				signal.addEventListener("abort", () => reject(signal.reason));
+			});
+		},
+	});
+	const harness = await testPlugin(plugin, {
+		apiKeys: { "openai-codex": token("acct-1") },
+	});
+	const turn = new AbortController();
+	const reason = new Error("the turn ended");
+	const drawing = plugin.providers?.images?.("a fox", [], {
+		signal: turn.signal,
+	});
+	const outcome = drawing?.then(
+		() => undefined,
+		(error: unknown) => error,
+	);
+	await new Promise((done) => setTimeout(done, 20));
+	expect(signals[0]?.aborted).toBe(false);
+	turn.abort(reason);
+	expect(await outcome).toBe(reason);
+	expect(signals[0]?.aborted).toBe(true);
+	await harness.stop();
+});
+
 test("codex-images refuses to start without an openai-codex login", async () => {
 	const failure = await testPlugin(codexImages).then(
 		() => undefined,

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

@@ -3,238 +3,14 @@
 // as an API, so it can stop working without notice, and OpenAI's terms for the subscription
 // apply to it. Use it only where you accept that risk.
 
-import { definePlugin, PluginError, type ReferenceImage } from "pi-roundtable";
+import { createCodexImages } from "pi-roundtable/kit";
 
-const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
-/** The Pi provider whose login pays for the images. */
-const CODEX_PROVIDER = "openai-codex";
-/** Routes the Codex request; the backend picks the image model itself. */
-const CODEX_MODEL = "gpt-6-sol";
-const JWT_CLAIM_PATH = "https://api.openai.com/auth";
-const REQUEST_TIMEOUT_MS = 5 * 60_000;
-const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
-const MAX_IMAGE_BASE64 = Math.ceil(MAX_IMAGE_BYTES / 3) * 4;
-
-/**
- * Codex ran the image tool but returned no image, usually because it refused the prompt.
- * Asking again with the same prompt fails again.
- */
-export class ImageNotGeneratedError extends Error {
-	override name = "ImageNotGeneratedError";
-}
-
-/** The part of `fetch` the plugin uses, so a test can stand in for the network. */
-export type CodexFetch = (url: string, init: RequestInit) => Promise<Response>;
-
-export interface CodexImagesOptions {
-	/** The request function; default the global `fetch`. */
-	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. */
-function chatGptAccountId(token: string): string {
-	const [, payload] = token.split(".");
-	if (!payload) throw new Error("the Codex token is not a JWT");
-	let claims: Record<string, unknown>;
-	try {
-		claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-	} catch {
-		throw new Error("the Codex token's claims are not JSON");
-	}
-	const auth = claims[JWT_CLAIM_PATH] as
-		| { chatgpt_account_id?: unknown }
-		| undefined;
-	const id = auth?.chatgpt_account_id;
-	if (typeof id !== "string" || !id)
-		throw new Error("the Codex token has no ChatGPT account");
-	return id;
-}
-
-function object(value: unknown): Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value)
-		? (value as Record<string, unknown>)
-		: {};
-}
-
-/** The one image an `image_generation_call` item carries; anything else is not an image. */
-function imageOf(value: unknown): Uint8Array | undefined {
-	const item = object(value);
-	if (item.type !== "image_generation_call") return undefined;
-	if (
-		item.status !== "completed" ||
-		typeof item.result !== "string" ||
-		!item.result
-	) {
-		const { result: _result, ...detail } = item;
-		throw new ImageNotGeneratedError(
-			`Codex image generation did not complete (status ${String(item.status)}): ${JSON.stringify(detail).slice(0, 300)}`,
-		);
-	}
-	if (item.result.length > MAX_IMAGE_BASE64)
-		throw new Error("the image exceeds 32 MiB");
-	return new Uint8Array(Buffer.from(item.result, "base64"));
-}
-
-/** The frames of a server-sent event stream: the text between blank lines. */
-async function* frames(
-	body: ReadableStream<Uint8Array>,
-): AsyncGenerator<string> {
-	const decoder = new TextDecoder();
-	let buffer = "";
-	for await (const chunk of body) {
-		buffer += decoder.decode(chunk, { stream: true });
-		let match = /\r?\n\r?\n/.exec(buffer);
-		while (match) {
-			yield buffer.slice(0, match.index);
-			buffer = buffer.slice(match.index + match[0].length);
-			match = /\r?\n\r?\n/.exec(buffer);
-		}
-	}
-	if (buffer.trim()) yield buffer;
-}
-
-/** The event a frame carries, or undefined for a frame without data. */
-function eventOf(frame: string): Record<string, unknown> | undefined {
-	const data = frame
-		.split(/\r?\n/)
-		.flatMap((line) => (line.startsWith("data:") ? [line.slice(5).trim()] : []))
-		.join("\n");
-	if (!data || data === "[DONE]") return undefined;
-	try {
-		return object(JSON.parse(data));
-	} catch {
-		throw new Error(`Codex sent a malformed event: ${data.slice(0, 200)}`);
-	}
-}
-
-/** Reads the events until the response completes, and returns its one image. */
-async function parseImageStream(response: Response): Promise<Uint8Array> {
-	if (!response.body) throw new Error("Codex returned no body");
-	let image: Uint8Array | undefined;
-	for await (const frame of frames(response.body)) {
-		const event = eventOf(frame);
-		switch (event?.type) {
-			case "error":
-			case "response.failed": {
-				const error = object(object(event.response).error ?? event.error);
-				throw new Error(
-					`Codex failed: ${String(error.message ?? error.code ?? "unknown error")}`,
-				);
-			}
-			case "response.incomplete":
-				throw new Error("the Codex response was incomplete");
-			case "response.output_item.done":
-				image ??= imageOf(event.item);
-				break;
-			case "response.completed": {
-				const output = object(event.response).output;
-				if (Array.isArray(output))
-					for (const item of output) image ??= imageOf(item);
-				if (!image)
-					throw new ImageNotGeneratedError("Codex answered without an image");
-				return image;
-			}
-			default:
-				break;
-		}
-	}
-	throw new Error("the Codex stream ended before completion");
-}
-
-async function generateImage(
-	prompt: string,
-	references: readonly ReferenceImage[],
-	token: string,
-	model: string,
-	fetchImpl: CodexFetch,
-): Promise<Uint8Array> {
-	const response = await fetchImpl(CODEX_RESPONSES_URL, {
-		method: "POST",
-		redirect: "error",
-		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-		headers: {
-			authorization: `Bearer ${token}`,
-			"chatgpt-account-id": chatGptAccountId(token),
-			originator: "pi",
-			"openai-beta": "responses=experimental",
-			accept: "text/event-stream",
-			"content-type": "application/json",
-		},
-		body: JSON.stringify({
-			model,
-			store: false,
-			stream: true,
-			instructions:
-				"You are generating bitmap image assets. For this request, call the image_generation tool exactly once. Do not answer with only text unless image generation is unavailable.",
-			input: [
-				{
-					role: "user",
-					content: [
-						{ type: "input_text", text: prompt },
-						...references.map((image) => ({
-							type: "input_image",
-							image_url: `data:${image.mimeType};base64,${image.data}`,
-						})),
-					],
-				},
-			],
-			tools: [{ type: "image_generation", output_format: "png" }],
-			tool_choice: "auto",
-			parallel_tool_calls: false,
-			text: { verbosity: "low" },
-		}),
-	});
-	if (!response.ok) {
-		const detail = (await response.text()).slice(0, 300);
-		throw new Error(`Codex answered ${response.status}: ${detail}`);
-	}
-	return parseImageStream(response);
-}
-
-const NO_LOGIN = `the host has no login for ${CODEX_PROVIDER}, the provider that pays for the images. Log in to the ${CODEX_PROVIDER} provider with Pi so the agent directory's auth.json holds it, or remove this plugin.`;
-
-/** The plugin, with its request function and model replaceable for a test. */
-export function createCodexImages(options: CodexImagesOptions = {}) {
-	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> => {
-		const value = await apiKey?.(CODEX_PROVIDER);
-		if (!value) throw new PluginError(`plugin codex-images: ${NO_LOGIN}`);
-		return value;
-	};
-	return definePlugin({
-		name: "codex-images",
-		providers: {
-			// The images slot draws an agent's avatar from a prompt and reference pictures.
-			images: async (prompt, references) =>
-				generateImage(prompt, references, await token(), model, fetchImpl),
-		},
-		async setup(context) {
-			apiKey = context.apiKey;
-			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 {};
-		},
-	});
-}
+export {
+	type CodexFetch,
+	type CodexImagesOptions,
+	createCodexImages,
+	ImageNotGeneratedError,
+} from "pi-roundtable/kit";
 
+/** The plugin the project lists. The client and the plugin are the kit's; this file is yours to change. */
 export const codexImages = createCodexImages();

package/templates/package.json.tmpl

@@ -15,11 +15,11 @@
 	"dependencies": {
 		"pi-roundtable": "__VERSION__",
 		"pi-self-compact": "0.2.0",
-		"typebox": "1.3.34"
+		"typebox": "1.3.37"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.15",
-		"@types/bun": "1.4.2",
+		"@types/bun": "1.4.3",
 		"typescript": "7.0.2"
 	}
 }