pi-roundtable 0.2.1 → 0.4.0

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

@@ -0,0 +1,215 @@
+// Warning: this plugin uses ChatGPT's undocumented Codex backend, signed in with the owner's own
+// ChatGPT subscription (the `openai-codex` login), to draw images. OpenAI has not published it
+// 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";
+
+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;
+}
+
+/** The ChatGPT account the login token belongs to, from the token's claims. */
+function chatGptAccountId(token: string): string {
+	const payload = token.split(".")[1];
+	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>)
+		: {};
+}
+
+/** Reads the server-sent 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;
+	let completed = false;
+	const take = (value: unknown) => {
+		const item = object(value);
+		if (item.type !== "image_generation_call" || image) return;
+		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");
+		image = new Uint8Array(Buffer.from(item.result, "base64"));
+	};
+	const handle = (frame: string) => {
+		const data = frame
+			.split(/\r?\n/)
+			.filter((line) => line.startsWith("data:"))
+			.map((line) => line.slice(5).trim())
+			.join("\n");
+		if (!data || data === "[DONE]") return;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(data);
+		} catch {
+			throw new Error(`Codex sent a malformed event: ${data.slice(0, 200)}`);
+		}
+		const event = object(parsed);
+		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":
+				take(event.item);
+				break;
+			case "response.completed": {
+				const output = object(event.response).output;
+				if (!image && Array.isArray(output))
+					for (const item of output) take(item);
+				completed = true;
+				break;
+			}
+		}
+	};
+	const decoder = new TextDecoder();
+	let buffer = "";
+	for await (const chunk of response.body) {
+		buffer += decoder.decode(chunk, { stream: true });
+		let match = /\r?\n\r?\n/.exec(buffer);
+		while (match && !completed) {
+			handle(buffer.slice(0, match.index));
+			buffer = buffer.slice(match.index + match[0].length);
+			match = /\r?\n\r?\n/.exec(buffer);
+		}
+		if (completed) break;
+	}
+	if (!completed && buffer.trim()) handle(buffer);
+	if (!completed) throw new Error("the Codex stream ended before completion");
+	if (!image)
+		throw new ImageNotGeneratedError("Codex answered without an image");
+	return image;
+}
+
+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 } = 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;
+			await token();
+			return {};
+		},
+	});
+}
+
+export const codexImages = createCodexImages();

package/templates/official/dice/plugin.test.ts.tmpl

@@ -0,0 +1,105 @@
+import { expect, test } from "bun:test";
+import { testPlugin } from "pi-roundtable/testing";
+import { createDice, dice, type Random, roll } from "./dice.ts";
+
+/** A random source that answers with the faces given, as `[face, sides]` for each die in turn. */
+function dieFaces(...rolled: [face: number, sides: number][]): Random {
+	const queue = rolled.map(([face, sides]) => (face - 1) / sides + 0.0001);
+	return () => {
+		const next = queue.shift();
+		if (next === undefined)
+			throw new Error("the test rolled more dice than it gave");
+		return next;
+	};
+}
+
+/** The faces given, for dice that all have `sides` sides. */
+const faces = (sides: number, ...rolled: number[]): Random =>
+	dieFaces(...rolled.map((face): [number, number] => [face, sides]));
+
+test("a die rolls from 1 to its sides, and a number adds itself", () => {
+	expect(roll("2d6+3", faces(6, 3, 5))).toBe("2d6+3: [3, 5] + 3 = 11");
+	expect(roll("d20", faces(20, 20))).toBe("d20: [20] = 20");
+	expect(roll(" 1D4 ", faces(4, 1))).toBe("1D4: [1] = 1");
+});
+
+test("several groups add and subtract in order", () => {
+	expect(roll("2d6-1d4+2", dieFaces([4, 6], [2, 6], [1, 4]))).toBe(
+		"2d6-1d4+2: [4, 2] - [1] + 2 = 7",
+	);
+	expect(roll("-d6", faces(6, 2))).toBe("-d6: -[2] = -2");
+});
+
+test("keep and drop rules remove dice and show them in parentheses", () => {
+	const six = (...rolled: number[]) => faces(6, ...rolled);
+	expect(roll("4d6k3", six(5, 1, 6, 3))).toBe("4d6k3: [5, (1), 6, 3] = 14");
+	expect(roll("4d6kh3", six(5, 1, 6, 3))).toBe("4d6kh3: [5, (1), 6, 3] = 14");
+	expect(roll("4d6kl1", six(5, 1, 6, 3))).toBe(
+		"4d6kl1: [(5), 1, (6), (3)] = 1",
+	);
+	expect(roll("4d6d1", six(5, 1, 6, 3))).toBe("4d6d1: [5, (1), 6, 3] = 14");
+	expect(roll("4d6dl1", six(5, 1, 6, 3))).toBe("4d6dl1: [5, (1), 6, 3] = 14");
+	expect(roll("4d6dh1", six(5, 1, 6, 3))).toBe("4d6dh1: [5, 1, (6), 3] = 9");
+});
+
+test("fate dice add -1, 0, and +1 and default to four", () => {
+	const random = (() => {
+		const queue = [0.1, 0.5, 0.9, 0.9];
+		return () => queue.shift() ?? 0;
+	})();
+	expect(roll("dF", random)).toBe("dF: [-, 0, +, +] = 1");
+});
+
+test("a bad expression is refused with what to fix", () => {
+	for (const bad of [
+		"",
+		"   ",
+		"abc",
+		"2d",
+		"d1",
+		"0d6",
+		"2d6+",
+		"2d6++1",
+		"2d6 d4",
+		"4d6k4",
+		"4d6k0",
+		"4d6d9",
+		"1d6x",
+	])
+		expect(() => roll(bad, () => 0.5)).toThrow("Write an expression such as");
+});
+
+test("the caps on dice, sides, and length are refused", () => {
+	expect(() => roll("101d6", () => 0.5)).toThrow("more than 100 dice");
+	expect(() => roll("60d6+60d6", () => 0.5)).toThrow(
+		"more than 100 dice in all",
+	);
+	expect(() => roll("1d1001", () => 0.5)).toThrow("between 2 and 1000 sides");
+	expect(() => roll("d6+1000001", () => 0.5)).toThrow("is over 1000000");
+	expect(() => roll(`1+${"1+".repeat(120)}1`, () => 0.5)).toThrow(
+		"over 200 characters",
+	);
+	expect(roll("100d2", () => 0.99)).toContain("= 200");
+	expect(roll("1d1000", () => 0.9999)).toBe("1d1000: [1000] = 1000");
+});
+
+test("the roll_dice tool is for members and answers a bad expression as text", async () => {
+	const harness = await testPlugin(createDice(faces(6, 3, 5)));
+	expect(harness.tools).toEqual(["roll_dice"]);
+	expect(harness.tiers.minTier("roll_dice")).toBe("member");
+	expect(await harness.runTool("roll_dice", { expression: "2d6+3" })).toBe(
+		"2d6+3: [3, 5] + 3 = 11",
+	);
+	expect(await harness.runTool("roll_dice", { expression: "nope" })).toContain(
+		"is not a dice term",
+	);
+	await harness.stop();
+});
+
+test("the ready-made plugin rolls with a real random source", async () => {
+	const harness = await testPlugin(dice);
+	expect(await harness.runTool("roll_dice", { expression: "d6" })).toMatch(
+		/^d6: \[[1-6]\] = [1-6]$/,
+	);
+	await harness.stop();
+});

package/templates/official/dice/plugin.ts

@@ -0,0 +1,166 @@
+import { definePlugin, defineTool, ToolRefusal } from "pi-roundtable";
+import { Type } from "typebox";
+
+/** Returns a number from 0 up to, not including, 1, like `Math.random`. */
+export type Random = () => number;
+
+const MAX_DICE = 100;
+const MAX_SIDES = 1000;
+const MAX_LENGTH = 200;
+const MAX_MODIFIER = 1_000_000;
+const FATE_DEFAULT = 4;
+
+type KeepDrop = "k" | "kh" | "kl" | "d" | "dh" | "dl";
+
+const TERM = /^(\d*)d(?:(f)|(\d+)(?:(kh|kl|dh|dl|k|d)(\d+))?)$/;
+
+const refuse = (problem: string): never => {
+	throw new ToolRefusal(
+		`${problem} Write an expression such as 2d6+3, d20, 4d6k3, or 4dF.`,
+	);
+};
+
+/** The indexes a keep or drop rule removes; `rolls` has more than `n` dice. */
+function removed(
+	rolls: readonly number[],
+	rule: KeepDrop,
+	n: number,
+): number[] {
+	const ascending = rolls
+		.map((value, index) => ({ value, index }))
+		.sort((a, b) => a.value - b.value || a.index - b.index)
+		.map((die) => die.index);
+	switch (rule) {
+		case "k":
+		case "kh":
+			return ascending.slice(0, rolls.length - n);
+		case "kl":
+			return ascending.slice(n);
+		case "d":
+		case "dl":
+			return ascending.slice(0, n);
+		case "dh":
+			return ascending.slice(rolls.length - n);
+	}
+}
+
+/** One term rolled: what it shows, and what it adds before its sign applies. */
+interface Rolled {
+	shown: string;
+	value: number;
+	dice: number;
+}
+
+function rollTerm(term: string, random: Random): Rolled {
+	if (/^\d+$/.test(term)) {
+		if (term.length > 7 || Number(term) > MAX_MODIFIER)
+			return refuse(`The number ${term} is over ${MAX_MODIFIER}.`);
+		return { shown: String(Number(term)), value: Number(term), dice: 0 };
+	}
+	const match = TERM.exec(term);
+	if (!match) return refuse(`"${term}" is not a dice term.`);
+	const [, countText, fate, sidesText, rule, nText] = match;
+	const count = countText ? Number(countText) : fate ? FATE_DEFAULT : 1;
+	if (count < 1) return refuse(`"${term}" rolls no dice.`);
+	if (count > MAX_DICE)
+		return refuse(`"${term}" rolls more than ${MAX_DICE} dice.`);
+	if (fate) {
+		const faces = Array.from(
+			{ length: count },
+			() => Math.floor(random() * 3) - 1,
+		);
+		const symbols = faces.map((face) =>
+			face > 0 ? "+" : face < 0 ? "-" : "0",
+		);
+		return {
+			shown: `[${symbols.join(", ")}]`,
+			value: faces.reduce((sum, face) => sum + face, 0),
+			dice: count,
+		};
+	}
+	const sides = Number(sidesText);
+	if (sides < 2 || sides > MAX_SIDES)
+		return refuse(`"${term}" needs between 2 and ${MAX_SIDES} sides.`);
+	const rolls = Array.from(
+		{ length: count },
+		() => Math.floor(random() * sides) + 1,
+	);
+	const dropped = new Set<number>();
+	if (rule) {
+		const n = Number(nText);
+		if (n < 1 || n >= count)
+			return refuse(
+				`"${term}" must keep or drop at least 1 and fewer than ${count} dice.`,
+			);
+		for (const index of removed(rolls, rule as KeepDrop, n)) dropped.add(index);
+	}
+	const shown = rolls.map((value, index) =>
+		dropped.has(index) ? `(${value})` : String(value),
+	);
+	return {
+		shown: `[${shown.join(", ")}]`,
+		value: rolls.reduce(
+			(sum, value, index) => sum + (dropped.has(index) ? 0 : value),
+			0,
+		),
+		dice: count,
+	};
+}
+
+/**
+ * Rolls an expression of dice terms and numbers joined by `+` and `-`, and writes the result as
+ * text such as `2d6+3: [3, 5] + 3 = 11`. A term is `NdS`, an optional keep or drop rule
+ * (`k`/`kh` keep the highest, `kl` the lowest, `d`/`dl` drop the lowest, `dh` the highest, each
+ * with a count), `NdF` fate dice (default 4), or a whole number. Dropped dice show in parentheses.
+ * An invalid or oversized expression throws a `ToolRefusal` that says what to fix.
+ */
+export function roll(expression: string, random: Random = Math.random): string {
+	const compact = expression.replace(/\s+/g, "");
+	if (!compact) return refuse("The expression is empty.");
+	if (compact.length > MAX_LENGTH)
+		return refuse(`The expression is over ${MAX_LENGTH} characters.`);
+	const parts = [...compact.toLowerCase().matchAll(/([+-]?)([^+-]+)/g)];
+	if (parts.map((part) => part[0]).join("") !== compact.toLowerCase())
+		return refuse(`"${compact}" is not a sum of dice and numbers.`);
+	let total = 0;
+	let dice = 0;
+	let line = "";
+	for (const [index, [, sign = "", term = ""]] of parts.entries()) {
+		if (index > 0 && !sign)
+			return refuse(`"${compact}" is not a sum of dice and numbers.`);
+		const rolled = rollTerm(term, random);
+		dice += rolled.dice;
+		if (dice > MAX_DICE)
+			return refuse(`The expression rolls more than ${MAX_DICE} dice in all.`);
+		total += sign === "-" ? -rolled.value : rolled.value;
+		line +=
+			index === 0
+				? `${sign === "-" ? "-" : ""}${rolled.shown}`
+				: ` ${sign} ${rolled.shown}`;
+	}
+	return `${compact}: ${line} = ${total}`;
+}
+
+/** The plugin, with the random source replaceable for a test. */
+export function createDice(random: Random = Math.random) {
+	return definePlugin({
+		name: "dice",
+		setup: () => ({
+			tools: [
+				defineTool({
+					name: "roll_dice",
+					description: `Roll dice and report each die and the total. The expression joins terms with + and -: NdS rolls N dice of S sides (2d6, d20), a count after k/kh keeps the highest dice (4d6k3), kl keeps the lowest, d/dl drops the lowest, dh drops the highest, NdF rolls N fate dice (default 4), and a plain number adds itself (2d6+1d4-1). At most ${MAX_DICE} dice in all and ${MAX_SIDES} sides per die. Dropped dice show in parentheses.`,
+					parameters: Type.Object({
+						expression: Type.String({
+							description: "For example 2d6+3 or 4d6k3",
+						}),
+					}),
+					minTier: "member",
+					run: ({ expression }) => roll(expression, random),
+				}),
+			],
+		}),
+	});
+}
+
+export const dice = createDice();