@rigelbuild/omp-catalog 18.0.3

package/src/wire/alibaba-token-plan.ts

@@ -0,0 +1,54 @@
+/**
+ * International (Singapore) Token Plan endpoint. Default region; keys issued by
+ * the international product authenticate only here.
+ */
+export const ALIBABA_TOKEN_PLAN_BASE_URL = "https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1";
+/**
+ * China (Beijing) Token Plan endpoint (百炼 Token Plan). Keys are region-locked:
+ * a Beijing-issued key is rejected by the international endpoint with
+ * `invalid_api_key`, and vice versa (#6682).
+ */
+export const ALIBABA_TOKEN_PLAN_CN_BASE_URL = "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1";
+
+export interface AlibabaTokenPlanCredential {
+	token: string;
+	cookie?: string;
+	/**
+	 * Region base URL the key authenticates against. Absent means the default
+	 * international endpoint ({@link ALIBABA_TOKEN_PLAN_BASE_URL}).
+	 */
+	baseUrl?: string;
+}
+
+const TOKEN_PATTERN = /^sk-[A-Za-z0-9._~+/-]+={0,2}$/;
+
+export function parseAlibabaTokenPlanCredential(value: string): AlibabaTokenPlanCredential | null {
+	const trimmed = value.trim();
+	if (!trimmed) return null;
+	if (!trimmed.startsWith("{")) return TOKEN_PATTERN.test(trimmed) ? { token: trimmed } : null;
+	try {
+		const parsed = JSON.parse(trimmed) as { token?: unknown; cookie?: unknown; baseUrl?: unknown };
+		if (typeof parsed.token !== "string" || !TOKEN_PATTERN.test(parsed.token.trim())) return null;
+		if (parsed.cookie !== undefined && typeof parsed.cookie !== "string") return null;
+		if (parsed.baseUrl !== undefined && typeof parsed.baseUrl !== "string") return null;
+		const token = parsed.token.trim();
+		const cookie = parsed.cookie?.trim();
+		const baseUrl = parsed.baseUrl?.trim();
+		const credential: AlibabaTokenPlanCredential = { token };
+		if (cookie) credential.cookie = cookie;
+		if (baseUrl) credential.baseUrl = baseUrl;
+		return credential;
+	} catch {
+		return null;
+	}
+}
+
+export function serializeAlibabaTokenPlanCredential(token: string, cookie: string, baseUrl?: string): string {
+	const trimmedCookie = cookie.trim();
+	const trimmedBaseUrl = baseUrl?.trim();
+	if (!trimmedCookie && !trimmedBaseUrl) return token;
+	const payload: { token: string; cookie?: string; baseUrl?: string } = { token };
+	if (trimmedCookie) payload.cookie = trimmedCookie;
+	if (trimmedBaseUrl) payload.baseUrl = trimmedBaseUrl;
+	return JSON.stringify(payload);
+}

package/src/wire/codex.ts

@@ -0,0 +1,117 @@
+/**
+ * Constants for OpenAI Codex (ChatGPT OAuth) backend
+ */
+
+export const CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+
+/**
+ * Pinned OpenAI Codex client version (corresponds to @openai/codex package version).
+ */
+export const CODEX_CLIENT_VERSION = "0.144.1";
+
+export const OPENAI_HEADERS = {
+	BETA: "OpenAI-Beta",
+	/** Codex feature-negotiation header; values identify opt-in wire protocols. */
+	CODEX_BETA_FEATURES: "x-codex-beta-features",
+	ACCOUNT_ID: "chatgpt-account-id",
+	ORIGINATOR: "originator",
+	VERSION: "version",
+	SESSION_ID: "session_id",
+	CONVERSATION_ID: "conversation_id",
+	SCOPED_SESSION_ID: "session-id",
+	THREAD_ID: "thread-id",
+	INSTALLATION_ID: "x-codex-installation-id",
+	WINDOW_ID: "x-codex-window-id",
+	TURN_METADATA: "x-codex-turn-metadata",
+	PARENT_THREAD_ID: "x-codex-parent-thread-id",
+	SUBAGENT: "x-openai-subagent",
+	/** Responses Lite transport marker (codex-rs `add_responses_lite_header`); value is always `"true"`. */
+	RESPONSES_LITE: "x-openai-internal-codex-responses-lite",
+	/** DeviceCheck attestation envelope (codex-rs `X_OAI_ATTESTATION_HEADER`); sent on ChatGPT-OAuth requests. */
+	ATTESTATION: "x-oai-attestation",
+	/** Client-declared data residency for region-pinned enterprise workspaces. */
+	RESIDENCY: "x-openai-internal-codex-residency",
+} as const;
+
+export const OPENAI_HEADER_VALUES = {
+	BETA_RESPONSES: "responses=experimental",
+	BETA_RESPONSES_WEBSOCKETS_V2: "responses_websockets=2026-02-06",
+	REMOTE_COMPACTION_V2: "remote_compaction_v2",
+	ORIGINATOR_CODEX: "pi",
+} as const;
+
+export const URL_PATHS = {
+	RESPONSES: "/responses",
+	CODEX_RESPONSES: "/codex/responses",
+} as const;
+
+export const JWT_CLAIM_PATH = "https://api.openai.com/auth" as const;
+
+/**
+ * Extract account ID from a Codex JWT access token.
+ * Returns undefined if the token is not a valid Codex JWT.
+ */
+export function getCodexAccountId(accessToken: string): string | undefined {
+	try {
+		const parts = accessToken.split(".");
+		if (parts.length !== 3) return undefined;
+		const decoded = Buffer.from(parts[1] ?? "", "base64").toString("utf-8");
+		const payload = JSON.parse(decoded) as Record<string, unknown>;
+		const auth = payload[JWT_CLAIM_PATH] as { chatgpt_account_id?: string } | undefined;
+		return auth?.chatgpt_account_id ?? undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Extract the account's data residency from a Codex JWT access token.
+ *
+ * Enterprise ChatGPT workspaces can be pinned to a region. Such a workspace
+ * rejects a Codex request whose egress does not match it — HTTP 401
+ * `Workspace is not authorized in this region.` — unless the client declares
+ * the residency itself. The token already carries it, so no configuration is
+ * needed: `chatgpt_data_residency` is the authoritative claim, with
+ * `chatgpt_compute_residency` as the fallback for tokens that only carry that.
+ *
+ * Returns undefined for a non-JWT token, or for the (common) accounts whose
+ * claims omit residency entirely — those workspaces are not region-pinned.
+ */
+export function getCodexResidency(accessToken: string): string | undefined {
+	try {
+		const parts = accessToken.split(".");
+		if (parts.length !== 3) return undefined;
+		const decoded = Buffer.from(parts[1] ?? "", "base64").toString("utf-8");
+		const payload = JSON.parse(decoded) as Record<string, unknown>;
+		const auth = payload[JWT_CLAIM_PATH] as
+			| { chatgpt_data_residency?: unknown; chatgpt_compute_residency?: unknown }
+			| undefined;
+		for (const claim of [auth?.chatgpt_data_residency, auth?.chatgpt_compute_residency]) {
+			if (typeof claim !== "string") continue;
+			const residency = claim.trim();
+			if (residency.length > 0) return residency;
+		}
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Adds the token's workspace residency to Codex request headers without
+ * replacing a caller-supplied value.
+ */
+export function applyCodexResidencyHeader(headers: Headers | Record<string, string>, accessToken: string): void {
+	const headerName = OPENAI_HEADERS.RESIDENCY;
+	if (headers instanceof Headers) {
+		if (headers.has(headerName)) return;
+		const residency = getCodexResidency(accessToken);
+		if (residency) headers.set(headerName, residency);
+		return;
+	}
+	for (const configuredName in headers) {
+		if (configuredName.toLowerCase() === headerName) return;
+	}
+	const residency = getCodexResidency(accessToken);
+	if (residency) headers[headerName] = residency;
+}

package/src/wire/coreweave.ts

@@ -0,0 +1,51 @@
+export const COREWEAVE_PROJECT_HEADER = "OpenAI-Project" as const;
+
+export interface CoreWeaveProjectEnv {
+	[key: string]: string | undefined;
+	COREWEAVE_PROJECT?: string;
+	WANDB_INFERENCE_PROJECT?: string;
+	WANDB_ENTITY?: string;
+	WANDB_PROJECT?: string;
+}
+
+function cleanEnvValue(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+export function resolveCoreWeaveProject(env: CoreWeaveProjectEnv): string | undefined {
+	const explicitProject = cleanEnvValue(env.COREWEAVE_PROJECT) ?? cleanEnvValue(env.WANDB_INFERENCE_PROJECT);
+	if (explicitProject) {
+		return explicitProject;
+	}
+
+	const wandbProject = cleanEnvValue(env.WANDB_PROJECT);
+	if (!wandbProject) {
+		return undefined;
+	}
+	if (wandbProject.includes("/")) {
+		return wandbProject;
+	}
+
+	const wandbEntity = cleanEnvValue(env.WANDB_ENTITY);
+	return wandbEntity ? `${wandbEntity}/${wandbProject}` : undefined;
+}
+
+export function coreWeaveProjectHeaders(env: CoreWeaveProjectEnv): Record<string, string> | undefined {
+	const project = resolveCoreWeaveProject(env);
+	return project ? { [COREWEAVE_PROJECT_HEADER]: project } : undefined;
+}
+
+export function hasCoreWeaveProjectHeader(headers: Record<string, string>): boolean {
+	const normalized = COREWEAVE_PROJECT_HEADER.toLowerCase();
+	return Object.entries(headers).some(([header, value]) => header.toLowerCase() === normalized && value.trim() !== "");
+}
+
+export function removeBlankCoreWeaveProjectHeaders(headers: Record<string, string>): void {
+	const normalized = COREWEAVE_PROJECT_HEADER.toLowerCase();
+	for (const [header, value] of Object.entries(headers)) {
+		if (header.toLowerCase() === normalized && value.trim() === "") {
+			delete headers[header];
+		}
+	}
+}

package/src/wire/gemini-headers.ts

@@ -0,0 +1,135 @@
+import type { FetchImpl } from "@rigelbuild/omp-utils";
+
+/**
+ * Build a User-Agent string that identifies as Gemini CLI to unlock higher rate limits.
+ * Uses the same format as the official Gemini CLI (v0.35+):
+ * GeminiCLI/VERSION/MODEL (PLATFORM; ARCH; SURFACE)
+ */
+export function getGeminiCliUserAgent(modelId = "gemini-3.1-pro-preview"): string {
+	const version = process.env.PI_AI_GEMINI_CLI_VERSION || "0.46.0";
+	const platform = process.platform === "win32" ? "win32" : process.platform;
+	const arch = process.arch === "x64" ? "x64" : process.arch;
+	return `GeminiCLI/${version}/${modelId} (${platform}; ${arch}; terminal)`;
+}
+
+export const getGeminiCliHeaders = (modelId?: string) => ({
+	"User-Agent": getGeminiCliUserAgent(modelId),
+	"Client-Metadata": "ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI",
+});
+
+/**
+ * Antigravity / Cloud Code Assist user agent. Lives in its own file so discovery
+ * and usage code can read it without pulling the heavy google-gemini-cli provider
+ * (and its @google/genai → google-auth-library dependency chain) into the startup
+ * parse graph.
+ *
+ * Format captured from the real 2.8.0 `antigravity/hub` client:
+ * `antigravity/hub/2.8.0 (aidev_client; os_type=darwin; arch=arm64; cl=963137146)`.
+ * The backend gates newer models (e.g. gemini-3.7-flash) on the client version,
+ * so the version tracks the latest Antigravity release via the update manifest
+ * (see {@link ensureAntigravityVersion}) with `DEFAULT_ANTIGRAVITY_VERSION` as
+ * the offline fallback. os_type/arch are pinned to the darwin/arm64 reference
+ * client the version and manifest are captured from, independent of the host
+ * platform. Overrides: PI_AI_ANTIGRAVITY_VERSION / _CL / _OS / _ARCH.
+ */
+export const DEFAULT_ANTIGRAVITY_VERSION = "2.8.0";
+
+const ANTIGRAVITY_VERSION_MANIFEST_URL =
+	"https://antigravity-hub-auto-updater-974169037036.us-central1.run.app/manifest/latest-arm64-mac.yml";
+const ANTIGRAVITY_VERSION_FETCH_TIMEOUT_MS = 5_000;
+
+let discoveredAntigravityVersion: string | null = null;
+let antigravityVersionFetch: Promise<void> | null = null;
+
+/** Current Antigravity client version: env override → manifest-discovered → pinned fallback. */
+export function getAntigravityVersion(): string {
+	return process.env.PI_AI_ANTIGRAVITY_VERSION || discoveredAntigravityVersion || DEFAULT_ANTIGRAVITY_VERSION;
+}
+
+/**
+ * Extracts the client version from an electron-builder update manifest.
+ * Returns null when no well-formed `version:` line is present.
+ */
+export function parseAntigravityManifestVersion(yamlText: string): string | null {
+	for (const line of yamlText.split(/\r?\n/)) {
+		const match = /^\s*version\s*:\s*(?:"([^"]*)"|'([^']*)'|([^\s#]+))\s*(?:#.*)?$/.exec(line);
+		if (!match) continue;
+		const version = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+		return /^\d+\.\d+\.\d+$/.test(version) ? version : null;
+	}
+	return null;
+}
+
+/**
+ * Resolves the latest Antigravity release from the official update manifest.
+ * Success is cached for the process lifetime; failures are silent (the pinned
+ * fallback stays valid) and clear the in-flight cache so a later call retries.
+ * Skipped entirely when PI_AI_ANTIGRAVITY_VERSION is set.
+ */
+export function ensureAntigravityVersion(fetcher: FetchImpl = fetch, signal?: AbortSignal): Promise<void> {
+	if (process.env.PI_AI_ANTIGRAVITY_VERSION || discoveredAntigravityVersion) return Promise.resolve();
+	if (antigravityVersionFetch) return antigravityVersionFetch;
+
+	antigravityVersionFetch = (async () => {
+		try {
+			const timeoutSignal = AbortSignal.timeout(ANTIGRAVITY_VERSION_FETCH_TIMEOUT_MS);
+			const response = await fetcher(ANTIGRAVITY_VERSION_MANIFEST_URL, {
+				headers: { "Cache-Control": "no-cache", "User-Agent": "electron-builder" },
+				signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal,
+			});
+			if (response.ok) {
+				discoveredAntigravityVersion = parseAntigravityManifestVersion(await response.text());
+			}
+		} catch {
+			// Silent: the pinned fallback remains valid when version discovery fails.
+		} finally {
+			if (!discoveredAntigravityVersion) antigravityVersionFetch = null;
+		}
+	})();
+	return antigravityVersionFetch;
+}
+
+/** Antigravity `User-Agent` header value; rebuilt when the discovered version changes. */
+export function getAntigravityUserAgent(): string {
+	const version = getAntigravityVersion();
+	// The backend does not validate `cl` (verified live: stale, zero, and absent
+	// cl all pass model gating on daily-cloudcode-pa; only the version gates).
+	// The update manifest carries no changelist, so the captured value stays.
+	const cl = process.env.PI_AI_ANTIGRAVITY_CL || "963137146";
+	const os = process.env.PI_AI_ANTIGRAVITY_OS || "darwin";
+	const arch = process.env.PI_AI_ANTIGRAVITY_ARCH || "arm64";
+	return `antigravity/hub/${version} (aidev_client; os_type=${os}; arch=${arch}; cl=${cl})`;
+}
+
+/**
+ * Per-wire-id Antigravity Cloud Code Assist request constants, captured from the
+ * real `antigravity/hub` client against `daily-cloudcode-pa`. `modelEnum` is the
+ * opaque `labels.model_enum` token the client tags each request with — optional
+ * because Anthropic-backed wire ids (e.g. `claude-sonnet-4-6`,
+ * `claude-opus-4-6-thinking`) are accepted without one; the label is purely
+ * telemetry. `maxOutputTokens` is the fixed `generationConfig.maxOutputTokens`
+ * the backend enforces regardless of the thinking budget (Claude caps at
+ * 64000, Gemini accepts the discovered cap). Keyed by the routed upstream wire
+ * id (post effort-routing), not the collapsed logical id. Checkpoint-only ids
+ * (e.g. `gemini-3.1-flash-lite`) are intentionally absent — this provider only
+ * emits agent requests.
+ */
+export interface AntigravityModelWireProfile {
+	modelEnum?: string;
+	maxOutputTokens: number;
+}
+export const ANTIGRAVITY_MODEL_WIRE_PROFILES: Readonly<Record<string, AntigravityModelWireProfile>> = {
+	"gemini-3.5-flash-extra-low": { modelEnum: "MODEL_PLACEHOLDER_M187", maxOutputTokens: 65536 },
+	"gemini-3.5-flash-low": { modelEnum: "MODEL_PLACEHOLDER_M20", maxOutputTokens: 65536 },
+	"gemini-3-flash-agent": { modelEnum: "MODEL_PLACEHOLDER_M132", maxOutputTokens: 65536 },
+	"gemini-3.1-pro-low": { modelEnum: "MODEL_PLACEHOLDER_M36", maxOutputTokens: 65535 },
+	"gemini-pro-agent": { modelEnum: "MODEL_PLACEHOLDER_M16", maxOutputTokens: 65535 },
+	// Claude on `daily-cloudcode-pa` rejects `maxOutputTokens > 64000` with a
+	// 400 (`Request contains an invalid argument`). The model_enum label is
+	// untracked for these ids; the backend does not require it.
+	"claude-sonnet-4-6": { maxOutputTokens: 64000 },
+	"claude-opus-4-6-thinking": { maxOutputTokens: 64000 },
+};
+export function getAntigravityModelWireProfile(wireModelId: string): AntigravityModelWireProfile | undefined {
+	return ANTIGRAVITY_MODEL_WIRE_PROFILES[wireModelId];
+}

package/src/wire/github-copilot.ts

@@ -0,0 +1,147 @@
+import type { FetchImpl } from "../types";
+import { isRecord } from "../utils";
+
+/**
+ * GitHub Copilot wire metadata: API-key envelope parsing and endpoint
+ * derivation shared by catalog discovery and the pi-ai OAuth flow. The device
+ * login / token refresh flow lives in `@oh-my-pi/pi-ai`'s registry.
+ */
+
+export const COPILOT_USER_AGENT = "opencode/1.3.15" as const;
+
+export const OPENCODE_HEADERS = {
+	"User-Agent": COPILOT_USER_AGENT,
+} as const;
+
+/**
+ * Copilot API version sent on `api.githubcopilot.com` requests (`/models`,
+ * chat endpoints). Newer versions unlock tiered context metadata: `/models`
+ * reports the full long-context window in `capabilities.limits` plus per-tier
+ * boundaries/prices under `billing.token_prices.{default,long_context}`.
+ * Without it the endpoint serves default-tier limits only (e.g. 264k instead
+ * of 1M for Claude Opus). Never send this to `api.github.com` REST endpoints —
+ * they validate `X-GitHub-Api-Version` against the REST version vocabulary.
+ */
+export const COPILOT_API_VERSION = "2026-06-01" as const;
+
+/** Headers for `api.githubcopilot.com` (capi) requests: discovery, chat, policy. */
+export const COPILOT_API_HEADERS = {
+	...OPENCODE_HEADERS,
+	"X-GitHub-Api-Version": COPILOT_API_VERSION,
+} as const;
+
+type GitHubCopilotApiKeyPayload = {
+	token?: unknown;
+	enterpriseUrl?: unknown;
+	apiEndpoint?: unknown;
+};
+
+export type ParsedGitHubCopilotApiKey = {
+	accessToken: string;
+	enterpriseUrl?: string;
+	apiEndpoint?: string;
+};
+
+const PUBLIC_GITHUB_HOSTS = new Set(["api.github.com", "github.com", "www.github.com"]);
+
+export function isPublicGitHubHost(host: string): boolean {
+	return PUBLIC_GITHUB_HOSTS.has(host.trim().toLowerCase());
+}
+
+/** Canonical personal-Copilot API host. */
+export const PERSONAL_GITHUB_COPILOT_BASE_URL = "https://api.githubcopilot.com" as const;
+
+/** `true` when the resolved base URL is the canonical personal-Copilot host. */
+export function isPersonalGitHubCopilotBaseUrl(baseUrl: string | undefined): boolean {
+	return baseUrl === PERSONAL_GITHUB_COPILOT_BASE_URL;
+}
+
+export function normalizeGitHubCopilotEnterpriseDomain(input: string | undefined): string | undefined {
+	const trimmed = input?.trim();
+	if (!trimmed) return undefined;
+	const normalized = normalizeDomain(trimmed) ?? trimmed.toLowerCase();
+	if (!normalized || isPublicGitHubHost(normalized)) return undefined;
+	return normalized;
+}
+
+export function normalizeGitHubCopilotApiEndpoint(input: string | undefined): string | undefined {
+	const trimmed = input?.trim();
+	if (!trimmed?.startsWith("https://")) return undefined;
+	try {
+		const url = new URL(trimmed);
+		if (url.protocol !== "https:" || !url.hostname) return undefined;
+		return trimmed.replace(/\/+$/, "");
+	} catch {
+		return undefined;
+	}
+}
+/**
+ * Resolve the plan-specific Copilot API endpoint advertised for a GitHub token.
+ * Login and raw environment-token discovery share this best-effort probe. Pass
+ * a `signal` to bound it against the same discovery deadline as `/models`; a
+ * stalled probe otherwise blocks discovery indefinitely.
+ */
+export async function discoverGitHubCopilotApiEndpoint(
+	token: string,
+	fetchImpl: FetchImpl,
+	signal?: AbortSignal,
+): Promise<string | undefined> {
+	try {
+		const response = await fetchImpl("https://api.github.com/copilot_internal/user", {
+			headers: {
+				Accept: "application/json",
+				Authorization: `token ${token}`,
+				...OPENCODE_HEADERS,
+			},
+			signal,
+		});
+		if (!response.ok) return undefined;
+		const data: unknown = await response.json();
+		if (!isRecord(data) || !isRecord(data.endpoints)) return undefined;
+		const endpoint = data.endpoints.api;
+		return typeof endpoint === "string" ? normalizeGitHubCopilotApiEndpoint(endpoint) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function parseGitHubCopilotApiKey(apiKeyRaw: string): ParsedGitHubCopilotApiKey {
+	try {
+		const parsed = JSON.parse(apiKeyRaw) as GitHubCopilotApiKeyPayload;
+		if (typeof parsed.token === "string") {
+			return {
+				accessToken: parsed.token,
+				enterpriseUrl:
+					typeof parsed.enterpriseUrl === "string"
+						? normalizeGitHubCopilotEnterpriseDomain(parsed.enterpriseUrl)
+						: undefined,
+				apiEndpoint:
+					typeof parsed.apiEndpoint === "string"
+						? normalizeGitHubCopilotApiEndpoint(parsed.apiEndpoint)
+						: undefined,
+			};
+		}
+	} catch {}
+
+	return { accessToken: apiKeyRaw };
+}
+
+export function normalizeDomain(input: string): string | null {
+	const trimmed = input.trim();
+	if (!trimmed) return null;
+	try {
+		const url = trimmed.includes("://") ? new URL(trimmed) : new URL(`https://${trimmed}`);
+		return url.hostname;
+	} catch {
+		return null;
+	}
+}
+
+export function getGitHubCopilotBaseUrl(enterpriseDomain?: string): string {
+	const normalizedEnterpriseDomain = normalizeGitHubCopilotEnterpriseDomain(enterpriseDomain);
+	if (!normalizedEnterpriseDomain) return "https://api.githubcopilot.com";
+	const host = normalizedEnterpriseDomain.startsWith("copilot-api.")
+		? normalizedEnterpriseDomain
+		: `copilot-api.${normalizedEnterpriseDomain}`;
+	return `https://${host}`;
+}

package/src/wire/image-fetchers.ts

@@ -0,0 +1,159 @@
+/**
+ * Identification of provider-side image fetchers.
+ *
+ * A request may carry an image either inline (base64) or as a URL. With a URL,
+ * the provider's backend performs its own server-side GET against that URL, so
+ * a local blob server sees an inbound request from vendor infrastructure rather
+ * than from the client. This module names those fetchers, letting a blob server
+ * attribute an inbound GET to the vendor that issued it — which is how a caller
+ * learns where a request actually landed when a router sits between them and
+ * the model.
+ *
+ * NOT an authentication mechanism. Every value here is a request header chosen
+ * by the caller and is trivially forged. Authorize blob reads with an
+ * unguessable URL (single-use capability token, short TTL) and treat a fetcher
+ * match as attribution/telemetry only.
+ *
+ * Each entry was captured from a live fetch triggered by handing that vendor's
+ * API a URL-sourced image.
+ */
+
+/** Vendor whose infrastructure performed an inbound fetch. */
+export type ImageFetcherVendor = "openai" | "anthropic" | "xai" | "google";
+
+/** Registry key for a known fetcher. */
+export type ImageFetcherId =
+	| "openai-file-downloader"
+	| "anthropic-claude-user"
+	| "anthropic-claude-user-preview"
+	| "xai-image-api-fetch"
+	| "google";
+
+/** Request signature of one provider-side fetcher. */
+export interface ImageFetcherIdentity {
+	vendor: ImageFetcherVendor;
+	/** Human-readable name for logs and UI. */
+	label: string;
+	/**
+	 * `User-Agent` contract: an exact string for fetchers that send a fixed
+	 * value, or a pattern for those embedding a client version.
+	 */
+	userAgent: string | RegExp;
+	/**
+	 * Vendor-proprietary headers observed alongside the agent, used to
+	 * corroborate a `User-Agent` claim. Generic infrastructure headers
+	 * (`traceparent`, `x-cloud-trace-context`) are deliberately excluded: they
+	 * are emitted by unrelated infrastructure and corroborate nothing. Empty
+	 * means the agent string is the only available signal, so
+	 * {@link ImageFetcherMatch.corroborated} can never be true for that entry.
+	 */
+	markerHeaders: readonly string[];
+	/** API surface the capture came from. */
+	observedVia: string;
+	/** Operational caveats a blob server should account for. */
+	note?: string;
+}
+
+/**
+ * Known provider-side fetchers.
+ *
+ * Agent contracts do not overlap — exact strings never collide with the
+ * versioned patterns — so lookup order carries no meaning.
+ */
+export const IMAGE_FETCHERS: Readonly<Record<ImageFetcherId, ImageFetcherIdentity>> = {
+	"openai-file-downloader": {
+		vendor: "openai",
+		label: "OpenAI File Downloader",
+		userAgent: "OpenAI File Downloader",
+		markerHeaders: ["openai-internal-smokescreener"],
+		observedVia: "chatgpt.com/backend-api/codex/responses, input_image.image_url",
+		note: "Issues two near-simultaneous GETs per image; a blob server must treat a duplicate hit as expected rather than as replay.",
+	},
+	"anthropic-claude-user": {
+		vendor: "anthropic",
+		label: "Claude image fetcher",
+		userAgent: "Claude-User",
+		markerHeaders: [],
+		observedVia: "api.anthropic.com/v1/messages, image.source.type=url",
+		note: "Sends only generic trace headers, so the bare agent string is the sole signal. Distinct from the versioned Claude-User/<version> agent used for links appearing in conversation text.",
+	},
+	"anthropic-claude-user-preview": {
+		vendor: "anthropic",
+		label: "Claude link fetcher",
+		userAgent: /\bClaude-User\/\d+(?:\.\d+)*\b/,
+		markerHeaders: [],
+		observedVia:
+			"unsolicited fetch after a URL appeared in assistant output; never observed serving an image request",
+		note: "Not an image fetcher. Listed so a blob server can separate it from the image path instead of counting it as a provider image fetch.",
+	},
+	"xai-image-api-fetch": {
+		vendor: "xai",
+		label: "xAI image API fetch",
+		userAgent: /^XaiImageApiFetch\/\d+(?:\.\d+)*\s/,
+		markerHeaders: ["x-xaifetchid"],
+		observedVia: "api.x.ai/v1/responses, input_image.image_url",
+		note: "Sends an image-only `accept` allowlist and rejects any other content type before the model sees the response.",
+	},
+	google: {
+		vendor: "google",
+		label: "Google",
+		userAgent: "Google",
+		markerHeaders: [],
+		observedVia: "cloudcode-pa.googleapis.com v1internal:streamGenerateContent, fileData.fileUri",
+		note: "Weakest signal of the set: the agent string is a bare vendor name with no version and no proprietary header.",
+	},
+};
+
+/** Attribution outcome for one inbound request. */
+export interface ImageFetcherMatch {
+	id: ImageFetcherId;
+	identity: ImageFetcherIdentity;
+	/**
+	 * Whether every proprietary marker header for the matched identity is
+	 * present. Always false for identities declaring no markers — absence of
+	 * corroboration is not evidence against the match.
+	 */
+	corroborated: boolean;
+}
+
+/** Inbound header bag, as exposed by either `fetch` or a Node-style server. */
+export type InboundHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+
+function headerValue(headers: InboundHeaders, name: string): string | undefined {
+	if (headers instanceof Headers) return headers.get(name) ?? undefined;
+	const direct = headers[name];
+	if (direct !== undefined) return Array.isArray(direct) ? direct[0] : (direct as string);
+	for (const key in headers) {
+		if (key.toLowerCase() !== name) continue;
+		const value = headers[key];
+		return Array.isArray(value) ? value[0] : (value as string | undefined);
+	}
+	return undefined;
+}
+
+/**
+ * Attribute an inbound blob request to a known provider-side fetcher, or
+ * `null` when the agent matches none.
+ *
+ * Matches on `User-Agent` alone and reports marker-header corroboration
+ * separately; callers MUST NOT treat either as proof of origin. Gate access on
+ * the unguessable URL.
+ */
+export function identifyImageFetcher(headers: InboundHeaders): ImageFetcherMatch | null {
+	const agent = headerValue(headers, "user-agent");
+	if (!agent) return null;
+	for (const id in IMAGE_FETCHERS) {
+		const identity = IMAGE_FETCHERS[id as ImageFetcherId];
+		const { userAgent } = identity;
+		const matched = typeof userAgent === "string" ? agent === userAgent : userAgent.test(agent);
+		if (!matched) continue;
+		return {
+			id: id as ImageFetcherId,
+			identity,
+			corroborated:
+				identity.markerHeaders.length > 0 &&
+				identity.markerHeaders.every(header => headerValue(headers, header) !== undefined),
+		};
+	}
+	return null;
+}