pi-codex-image-gen 0.1.12 → 0.1.14

package/src/codex-response.ts

@@ -0,0 +1,286 @@
+// The subscription Responses contract is private. Keep its parser and safety
+// boundaries separate from Pi tool registration and file handling.
+export const REQUEST_TIMEOUT_MS = 5 * 60_000;
+export const MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+export const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+const MAX_ERROR_BYTES = 16 * 1024;
+const MAX_TEXT_CHARS = 4000;
+
+export interface ReportedImage {
+	model?: string;
+	size?: string;
+	quality?: string;
+	background?: string;
+	outputFormat?: string;
+}
+
+export interface ParsedCodexResponse {
+	image?: {
+		id: string;
+		status: "completed";
+		result: string;
+		revisedPrompt?: string;
+		reported: ReportedImage;
+	};
+	text: string[];
+	responseId?: string;
+	usage?: unknown;
+}
+
+function object(value: unknown): Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown> : {};
+}
+
+function text(value: unknown, secrets: string[] = []): string {
+	if (typeof value !== "string") return "";
+	let result = value;
+	for (const secret of secrets) {
+		if (secret) result = result.split(secret).join("[redacted]");
+	}
+	// Also hide a JWT cut short by the text bound; exact-token matching alone
+	// cannot redact a credential that arrives across the truncation boundary.
+	return result.replace(/\beyJ[A-Za-z0-9_.-]*/g, "[redacted]")
+		.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, MAX_TEXT_CHARS);
+}
+
+function identifier(value: unknown, secrets: string[]): string | undefined {
+	return typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value)
+		&& !secrets.some(secret => secret && value.includes(secret)) ? value : undefined;
+}
+
+export function abortable<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const abort = () => reject(signal.reason);
+		if (signal.aborted) abort();
+		else signal.addEventListener("abort", abort, { once: true });
+		work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
+export async function withRequestDeadline<T>(
+	signal: AbortSignal | undefined,
+	run: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+	const controller = new AbortController();
+	const abort = () => controller.abort(new Error("Image generation was aborted."));
+	if (signal?.aborted) abort();
+	else signal?.addEventListener("abort", abort, { once: true });
+	const timer = setTimeout(() => controller.abort(new Error(
+		"Image generation timed out after 5 minutes. The backend may still finish; no automatic retry was made.",
+	)), REQUEST_TIMEOUT_MS);
+	try {
+		controller.signal.throwIfAborted();
+		return await run(controller.signal);
+	} catch (error) {
+		if (controller.signal.aborted) throw controller.signal.reason;
+		throw error;
+	} finally {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", abort);
+	}
+}
+
+async function* chunks(response: Response, limit: number, signal: AbortSignal): AsyncGenerator<Uint8Array> {
+	if (!response.body) throw new Error("Codex response did not include a stream body.");
+	const reader = response.body.getReader();
+	let bytes = 0;
+	try {
+		const declared = Number(response.headers.get("content-length"));
+		if (declared > limit) throw new Error("Codex response exceeded the size limit.");
+		while (true) {
+			signal.throwIfAborted();
+			let part: ReadableStreamReadResult<Uint8Array>;
+			try {
+				part = await abortable(reader.read(), signal);
+			} catch {
+				signal.throwIfAborted();
+				throw new Error("Codex response stream was interrupted. The backend may still finish; no automatic retry was made.");
+			}
+			const { done, value } = part;
+			if (done) break;
+			bytes += value.byteLength;
+			if (bytes > limit) throw new Error("Codex response exceeded the size limit.");
+			yield value;
+		}
+	} finally {
+		// Do not let a stalled stream cancellation defeat the request deadline.
+		void reader.cancel().catch(() => undefined);
+		reader.releaseLock();
+	}
+}
+
+const QUOTA_CODES = new Set([
+	"insufficient_quota", "quota_exceeded", "usage_limit_reached", "usage_limit_exceeded",
+	"billing_hard_limit_reached", "billing_not_active", "organization_usage_limit_exceeded",
+	"workspace_member_usage_limit_reached",
+]);
+
+function isQuota(error: Record<string, unknown>): boolean {
+	return [error.code, error.type].some(value => typeof value === "string" && QUOTA_CODES.has(value));
+}
+
+function errorHint(error: unknown): string {
+	const { code, type } = object(error);
+	if (isQuota({ code, type })) {
+		return "Codex subscription quota is unavailable or exhausted. Check your plan or wait for its reset.";
+	}
+	if (code === "moderation_blocked" || type === "image_generation_user_error") {
+		return "Codex could not generate this image. Review the prompt and input images before trying again.";
+	}
+	return "Codex could not complete the image request.";
+}
+
+export async function httpFailure(response: Response, signal: AbortSignal): Promise<{ message: string; retry: boolean }> {
+	if (response.headers.get("cf-mitigated") === "challenge") {
+		void response.body?.cancel().catch(() => undefined);
+		return { message: "Codex connection was challenged by Cloudflare. This does not establish model or subscription availability.", retry: false };
+	}
+	let body = "";
+	try {
+		const decoder = new TextDecoder();
+		for await (const chunk of chunks(response, MAX_ERROR_BYTES, signal)) body += decoder.decode(chunk, { stream: true });
+		body += decoder.decode();
+	} catch {
+		signal.throwIfAborted();
+		// A large or unreadable error body is deliberately not exposed.
+	}
+	let error: Record<string, unknown> = {};
+	try {
+		error = object(object(JSON.parse(body)).error);
+	} catch { /* HTML and other non-JSON error bodies are not diagnostics. */ }
+	const terminal = isQuota(error)
+		|| error.code === "moderation_blocked" || error.type === "image_generation_user_error";
+	const hint = response.status === 401
+		? "Image login was rejected. Run /login codex-images again."
+		: response.status === 403
+			? "Codex access was denied. This can be a connection or account restriction; it does not identify the image model."
+			: errorHint(error);
+	return {
+		message: `Codex image request failed (HTTP ${response.status}). ${hint}`,
+		retry: !terminal && [429, 500, 502, 503, 504].includes(response.status),
+	};
+}
+
+function reportedImage(item: Record<string, unknown>, secrets: string[]): ReportedImage {
+	const reported: ReportedImage = {};
+	const model = item.model;
+	if (typeof model === "string" && /^gpt-image-[a-z0-9.-]{1,80}$/.test(model)
+		&& !secrets.some(secret => secret && model.includes(secret))) reported.model = model;
+	if (typeof item.size === "string" && /^[1-9]\d{0,4}x[1-9]\d{0,4}$/.test(item.size)) reported.size = item.size;
+	if (typeof item.quality === "string" && ["low", "medium", "high", "xhigh", "max", "auto"].includes(item.quality)) reported.quality = item.quality;
+	if (typeof item.background === "string" && ["transparent", "opaque", "auto"].includes(item.background)) reported.background = item.background;
+	if (typeof item.output_format === "string" && ["png", "jpeg", "webp"].includes(item.output_format)) reported.outputFormat = item.output_format;
+	return reported;
+}
+
+export async function parseCodexSse(
+	response: Response,
+	signal: AbortSignal,
+	secrets: string[],
+	onProgress?: (stage: string) => void,
+): Promise<ParsedCodexResponse> {
+	const parsed: ParsedCodexResponse = { text: [] };
+	let completed = false;
+	let textChars = 0;
+	let lastStage: string | undefined;
+	const image = (value: unknown) => {
+		const item = object(value);
+		if (item.type !== "image_generation_call") return;
+		if (parsed.image) throw new Error("Codex returned more than one image. No automatic retry was made.");
+		if (item.status !== "completed") throw new Error("Codex image generation did not complete.");
+		if (typeof item.result !== "string" || !item.result) throw new Error("Codex image_generation_call did not contain image data.");
+		if (item.result.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4) throw new Error("Codex image exceeded the 32 MiB size limit.");
+		parsed.image = {
+			id: identifier(item.id, secrets) ?? "image_generation",
+			status: "completed",
+			result: item.result,
+			revisedPrompt: text(item.revised_prompt, secrets) || undefined,
+			reported: reportedImage(item, secrets),
+		};
+	};
+	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 event: Record<string, unknown>;
+		try { event = object(JSON.parse(data)); }
+		catch { throw new Error("Codex returned an invalid stream event. No automatic retry was made."); }
+		switch (event.type) {
+			case "error":
+			case "response.failed":
+				throw new Error(errorHint(object(event.response).error ?? event.error ?? event));
+			case "response.incomplete":
+				throw new Error("Codex response was incomplete. No automatic retry was made.");
+			case "response.created":
+				parsed.responseId = identifier(object(event.response).id, secrets);
+				break;
+			case "response.output_text.delta":
+				if (typeof event.delta === "string" && textChars < MAX_TEXT_CHARS) {
+					const delta = event.delta.slice(0, MAX_TEXT_CHARS - textChars);
+					parsed.text.push(delta);
+					textChars += delta.length;
+				}
+				break;
+			case "response.output_item.done":
+				image(event.item);
+				break;
+			case "response.completed": {
+				const final = object(event.response);
+				parsed.responseId = identifier(final.id, secrets) ?? parsed.responseId;
+				// Usage contains numeric counters only; never persist arbitrary response objects.
+				const usage = object(final.usage);
+				const counters: Record<string, unknown> = Object.fromEntries(
+					["input_tokens", "output_tokens", "total_tokens"].flatMap(key =>
+						typeof usage[key] === "number" && Number.isFinite(usage[key]) && usage[key] >= 0
+							? [[key, usage[key]]] : []),
+				);
+				for (const [key, fields] of [
+					["input_tokens_details", ["cached_tokens"]],
+					["output_tokens_details", ["reasoning_tokens"]],
+				] as const) {
+					const values = object(usage[key]);
+					const details = Object.fromEntries(fields.flatMap(field =>
+						typeof values[field] === "number" && Number.isFinite(values[field]) && values[field] >= 0
+							? [[field, values[field]]] : []));
+					if (Object.keys(details).length) counters[key] = details;
+				}
+				if (Object.keys(counters).length) parsed.usage = counters;
+				if (!parsed.image && Array.isArray(final.output)) final.output.forEach(image);
+				completed = true;
+				break;
+			}
+			case "response.image_generation_call.in_progress":
+			case "response.image_generation_call.generating":
+			case "response.image_generation_call.completed":
+				if (event.type !== lastStage) {
+					lastStage = event.type;
+					onProgress?.(event.type.split(".").at(-1)!);
+				}
+				break;
+		}
+	};
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let scanFrom = 0;
+	for await (const chunk of chunks(response, MAX_RESPONSE_BYTES, signal)) {
+		buffer += decoder.decode(chunk, { stream: true });
+		const separator = /\r?\n\r?\n/g;
+		separator.lastIndex = scanFrom;
+		let match: RegExpExecArray | null;
+		while ((match = separator.exec(buffer))) {
+			handle(buffer.slice(0, match.index));
+			buffer = buffer.slice(match.index + match[0].length);
+			if (completed) break;
+			separator.lastIndex = 0;
+		}
+		if (completed) break;
+		scanFrom = Math.max(0, buffer.length - 3);
+	}
+	if (!completed) {
+		buffer += decoder.decode();
+		if (buffer.trim()) handle(buffer);
+	}
+	if (!completed) throw new Error("Codex stream ended before completion. The backend may still finish; no automatic retry was made.");
+	parsed.text = [text(parsed.text.join(""), secrets)];
+	return parsed;
+}

package/src/image-oauth.ts

@@ -0,0 +1,223 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { OAuthAuth, OAuthCredential, Provider, ProviderAuthInteraction } from "@earendil-works/pi-ai";
+import { abortable } from "./codex-response.js";
+
+export const IMAGE_AUTH_PROVIDER = "codex-images";
+// Public OAuth client used by the image-capable ChatGPT/Codex flow.
+// This is a client identifier, not a secret. No Codex app or Pi legacy helper is used.
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
+const TOKEN_URL = "https://auth.openai.com/oauth/token";
+const REDIRECT_URI = "http://localhost:1455/auth/callback";
+const AUTH_CLAIM = "https://api.openai.com/auth";
+const LOGIN_TIMEOUT_MS = 10 * 60_000;
+const TOKEN_TIMEOUT_MS = 30_000;
+const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+const LOGIN_HINT = `Run /login ${IMAGE_AUTH_PROVIDER} again.`;
+
+class ImageOAuthDeniedError extends Error {
+	constructor() { super(`Image OAuth authorization was denied. ${LOGIN_HINT}`); }
+}
+
+export function extractImageAccountId(token: string): string {
+	try {
+		if (typeof token !== "string" || token.length > MAX_TOKEN_RESPONSE_BYTES
+			|| /[^a-zA-Z0-9_.-]/.test(token)) throw new Error();
+		const parts = token.split(".");
+		if (parts.length !== 3 || parts.some(part => !part)) throw new Error();
+		const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+		const accountId = payload?.[AUTH_CLAIM]?.chatgpt_account_id;
+		if (typeof accountId !== "string" || accountId.length === 0 || accountId.length > 128
+			|| /[^a-zA-Z0-9_-]/.test(accountId)) throw new Error();
+		// Routing hint only: OpenAI, not this client, authenticates the JWT.
+		return accountId;
+	} catch {
+		throw new Error(`Image OAuth token has no valid ChatGPT account ID. ${LOGIN_HINT}`);
+	}
+}
+
+export function parseImageOAuthCallback(input: string, state: string): string {
+	try {
+		if (input.length > 8192) throw new Error();
+		const url = new URL(input.trim());
+		const expected = new URL(REDIRECT_URI);
+		if (url.origin !== expected.origin || url.pathname !== expected.pathname || url.username || url.password || url.hash
+			|| url.searchParams.getAll("state").length !== 1 || url.searchParams.get("state") !== state) throw new Error();
+		if (url.searchParams.has("error")) throw new ImageOAuthDeniedError();
+		const codes = url.searchParams.getAll("code");
+		if (codes.length !== 1 || !codes[0] || codes[0].length > 4096) throw new Error();
+		return codes[0];
+	} catch (error) {
+		if (error instanceof ImageOAuthDeniedError) throw error;
+		throw new Error("Invalid image OAuth callback. Paste the full redirect URL from this login attempt.");
+	}
+}
+
+async function startCallback(state: string): Promise<{ server: Server; code: Promise<string> }> {
+	let settle!: (code: string) => void;
+	let reject!: (error: Error) => void;
+	const code = new Promise<string>((resolve, rejectCode) => { settle = resolve; reject = rejectCode; });
+	void code.catch(() => undefined);
+	let consumed = false;
+	const server = createServer((request, response) => {
+		if (request.method !== "GET" || consumed) {
+			response.writeHead(400).end("Invalid OAuth callback.");
+			return;
+		}
+		try {
+			const value = parseImageOAuthCallback(new URL(request.url ?? "/", REDIRECT_URI).href, state);
+			consumed = true;
+			response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" })
+				.end("Image login completed. You can close this window.");
+			settle(value);
+		} catch (error) {
+			// Do not reflect a code, state, or arbitrary query text into the page.
+			response.writeHead(400).end("Invalid OAuth callback. Return to Pi and retry.");
+			if (error instanceof ImageOAuthDeniedError) {
+				consumed = true;
+				reject(error);
+			}
+		}
+	});
+	server.headersTimeout = 15_000;
+	server.requestTimeout = 15_000;
+	try {
+		await new Promise<void>((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(1455, "127.0.0.1", () => {
+				server.removeListener("error", reject);
+				resolve();
+			});
+		});
+		server.on("error", () => reject(new Error(`Image OAuth callback failed. ${LOGIN_HINT}`)));
+		return { server, code };
+	} catch {
+		server.close();
+		throw new Error("Image OAuth callback listener is unavailable.");
+	}
+}
+
+async function requestTokens(body: URLSearchParams, signal: AbortSignal): Promise<OAuthCredential> {
+	const deadline = AbortSignal.any([signal, AbortSignal.timeout(TOKEN_TIMEOUT_MS)]);
+	try {
+		const response = await abortable(fetch(TOKEN_URL, {
+			method: "POST", redirect: "error", signal: deadline,
+			headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+			body,
+		}), deadline);
+		if (!response.ok) {
+			void response.body?.cancel().catch(() => undefined);
+			throw new Error();
+		}
+		if (Number(response.headers.get("content-length")) > MAX_TOKEN_RESPONSE_BYTES || !response.body) {
+			void response.body?.cancel().catch(() => undefined);
+			throw new Error();
+		}
+		const reader = response.body.getReader();
+		const blocks: Uint8Array[] = [];
+		let length = 0;
+		try {
+			while (true) {
+				const { done, value } = await abortable(reader.read(), deadline);
+				if (done) break;
+				length += value.byteLength;
+				if (length > MAX_TOKEN_RESPONSE_BYTES) throw new Error();
+				blocks.push(value);
+			}
+		} finally {
+			void reader.cancel().catch(() => undefined);
+			reader.releaseLock();
+		}
+		const data = JSON.parse(Buffer.concat(blocks).toString("utf8"));
+		if (typeof data?.access_token !== "string" || !data.access_token
+			|| typeof data.refresh_token !== "string" || !data.refresh_token
+			|| typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in) || data.expires_in <= 0) throw new Error();
+		const expires = Date.now() + data.expires_in * 1000;
+		if (!Number.isSafeInteger(expires)) throw new Error();
+		const accountId = extractImageAccountId(data.access_token);
+		return { type: "oauth", access: data.access_token, refresh: data.refresh_token, expires, accountId };
+	} catch {
+		// Never expose token responses, refresh tokens, codes, or fetch exceptions.
+		if (signal.aborted) throw new Error("Image OAuth was cancelled.");
+		throw new Error(`Image OAuth token exchange failed. ${LOGIN_HINT}`);
+	}
+}
+
+async function login(interaction: ProviderAuthInteraction): Promise<OAuthCredential> {
+	const deadline = AbortSignal.any([interaction.signal, AbortSignal.timeout(LOGIN_TIMEOUT_MS)]);
+	const manualAbort = new AbortController();
+	let callback: Awaited<ReturnType<typeof startCallback>> | undefined;
+	try {
+		deadline.throwIfAborted();
+		const state = randomBytes(32).toString("base64url");
+		const verifier = randomBytes(32).toString("base64url");
+		const challenge = createHash("sha256").update(verifier).digest("base64url");
+		try {
+			callback = await startCallback(state);
+		} catch {
+			interaction.notify({ type: "info", message: "The local callback port is unavailable. Paste the full redirect URL to finish image login." });
+		}
+		const url = new URL(AUTHORIZE_URL);
+		url.search = new URLSearchParams({
+			response_type: "code", client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,
+			scope: "openid profile email offline_access", state,
+			code_challenge: challenge, code_challenge_method: "S256",
+			id_token_add_organizations: "true", codex_cli_simplified_flow: "true",
+			originator: "pi",
+		}).toString();
+		interaction.notify({
+			type: "auth_url", url: url.href,
+			instructions: "Sign in with ChatGPT for image generation. This is separate from Pi's OpenAI chat login."
+				+ (callback ? "" : " The local callback port is unavailable. Paste the full redirect URL into Pi to finish login."),
+		});
+		const manual = interaction.prompt({
+			type: "manual_code",
+			message: callback ? "Complete image login in your browser, or paste the full redirect URL:"
+				: "The local callback port is unavailable. Paste the full redirect URL:",
+			placeholder: REDIRECT_URI, signal: AbortSignal.any([deadline, manualAbort.signal]),
+		}).then(input => parseImageOAuthCallback(input, state));
+		const code = await abortable(callback ? Promise.race([callback.code, manual]) : manual, deadline);
+		manualAbort.abort();
+		return await requestTokens(new URLSearchParams({
+			grant_type: "authorization_code", client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,
+			code, code_verifier: verifier,
+		}), deadline);
+	} catch (error) {
+		if (deadline.aborted) throw new Error("Image OAuth login was cancelled or timed out.");
+		throw error;
+	} finally {
+		manualAbort.abort();
+		callback?.server.close();
+		callback?.server.closeAllConnections();
+	}
+}
+
+export const imageOAuth: OAuthAuth = {
+	name: "Codex Images (ChatGPT subscription)",
+	isSubscription: true,
+	loginLabel: "Sign in with ChatGPT for images",
+	login,
+	async refresh(credential, signal) {
+		if (typeof credential.refresh !== "string" || !credential.refresh || credential.refresh.length > MAX_TOKEN_RESPONSE_BYTES) {
+			throw new Error(`Missing image OAuth refresh token. ${LOGIN_HINT}`);
+		}
+		return requestTokens(new URLSearchParams({
+			grant_type: "refresh_token", client_id: CLIENT_ID, refresh_token: credential.refresh,
+		}), signal);
+	},
+	async toAuth(credential) {
+		extractImageAccountId(credential.access);
+		return { apiKey: credential.access };
+	},
+};
+
+// Authentication-only provider: no chat models or model-picker entries.
+export const imageAuthProvider: Provider = {
+	id: IMAGE_AUTH_PROVIDER,
+	name: imageOAuth.name,
+	auth: { oauth: imageOAuth },
+	getModels: () => [],
+	stream() { throw new Error("Codex Images is an authentication-only provider. Use codex_generate_image."); },
+	streamSimple() { throw new Error("Codex Images is an authentication-only provider. Use codex_generate_image."); },
+};

package/src/install-telemetry.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const PACKAGE_NAME = "pi-codex-image-gen";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
 const CI_ENVIRONMENT_VARIABLES = [
   "APPVEYOR",
   "BITBUCKET_BUILD_NUMBER",
@@ -24,10 +23,6 @@ const CI_ENVIRONMENT_VARIABLES = [
   "VERCEL",
 ];
 
-interface InstallTelemetryState {
-  lastReportedVersion?: string;
-}
-
 interface PiSettingsDocument {
   enableInstallTelemetry?: unknown;
 }
@@ -51,18 +46,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isCiEnvironment(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return true;
-  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
-}
-
-function isInstallTelemetryEnabled(): boolean {
-  if (isCiEnvironment()) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as PiSettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {
@@ -70,35 +62,16 @@ function getPackageVersion(): string {
   return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
-}
-
-async function reportInstallTelemetryAsync(): Promise<void> {
+export function reportInstallTelemetry(): void {
   try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const extensionsDir = join(getAgentDir(), "extensions");
-    const statePath = join(extensionsDir, "pi-codex-image-gen-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(extensionsDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "pi-codex-image-gen-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
   } catch {
-    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+    // Best-effort telemetry: ignore local policy and filesystem failures.
   }
 }
-
-export function reportInstallTelemetry(): void {
-  void reportInstallTelemetryAsync();
-}