@geocine/pi-meta-oauth 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlockedPath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# pi-meta-oauth
+
+Meta Model API OAuth for [pi](https://pi.dev). Use Muse Spark models through Pi's `openai-responses` provider.
+
+## Install
+
+```bash
+pi install git:github.com/geocine/pi-meta-oauth@geocine
+pi --list-models meta
+```
+
+## Login
+
+```text
+/login meta
+```
+
+Pick browser login (device flow) or paste a Model API key. Device-flow keys are re-minted daily; pasted keys are stored as-is. Or skip login entirely with `META_API_KEY` / `MODEL_API_KEY`.
+
+## Models
+
+`muse-spark-1.3`, `muse-spark-1.3-contributor`, `muse-spark-1.2`, `muse-spark-1.2-contributor`, `muse-spark-1.1`
+
+## Verify
+
+```bash
+pi -p --provider meta --model muse-spark-1.3 "Reply exactly: META_OK"
+```

package/extensions/meta.ts

@@ -0,0 +1,851 @@
+import type {
+	Api,
+	Model,
+	ModelsStoreEntry,
+	OAuthCredentials,
+	OAuthLoginCallbacks,
+	RefreshModelsContext,
+} from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ProviderConfig,
+} from "@earendil-works/pi-coding-agent";
+
+export const META_PROVIDER_ID = "meta";
+export const META_API_BASE_URL = "https://api.meta.ai/v1";
+export const META_MODEL_CATALOG_URL = "https://api.meta.ai/v1/models";
+export const META_AUTH_BASE_URL = "https://auth.meta.com";
+export const META_CLIENT_ID = "1031625952748946";
+const META_ENV_VAR = "META_API_KEY";
+
+const DEVICE_AUTHORIZATION_URL = `${META_AUTH_BASE_URL}/oidc/device/authorization/`;
+const DEVICE_TOKEN_URL = `${META_AUTH_BASE_URL}/oidc/device/token/`;
+const API_KEY_MINT_URL = "https://api.meta.ai/muse-code/key";
+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+const API_KEY_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Marks credentials created by pasting a Model API key instead of the device
+ * flow. The marker lives in `refresh` (OAuthCredentials requires one), so
+ * refreshMetaToken can tell a static key from an identity token and must not
+ * send it to the mint endpoint.
+ */
+export const STATIC_API_KEY_PREFIX = "static-api-key:";
+
+export type MetaProviderModel = NonNullable<ProviderConfig["models"]>[number];
+type Fetch = typeof fetch;
+type Sleep = (milliseconds: number) => Promise<void>;
+
+interface DeviceAuthorization {
+	device_code: string;
+	user_code: string;
+	verification_uri: string;
+	verification_uri_complete?: string;
+	expires_in?: number;
+	interval?: number;
+}
+
+interface DeviceTokenGrant {
+	access_token: string;
+}
+
+interface OAuthError {
+	error?: string;
+	error_description?: string;
+}
+
+interface MintResponse {
+	api_key?: string;
+	base_url?: string;
+	require_payment?: boolean;
+	action_url?: string;
+}
+
+interface CatalogResponse {
+	data?: MetaCatalogModel[];
+}
+
+interface MetaCatalogModel {
+	id?: string;
+	metadata?: {
+		"muse-code"?: {
+			name?: string;
+			is_hidden?: boolean;
+			reasoning?: boolean;
+			modalities?: { input?: string[] };
+			limit?: { context?: number; output?: number };
+			variants?: Record<string, { reasoningEffort?: string }>;
+			cost?: {
+				input?: string | number;
+				output?: string | number;
+				cached?: string | number;
+			};
+		};
+	};
+}
+
+const FALLBACK_MODELS: MetaProviderModel[] = [
+	{
+		id: "muse-spark-1.3",
+		name: "Muse Spark 1.3",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: "max",
+		},
+		input: ["text", "image"],
+		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
+	{
+		id: "muse-spark-1.3-contributor",
+		name: "Muse Spark 1.3 Contributor",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,
+		},
+		input: ["text", "image"],
+		cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
+	{
+		id: "muse-spark-1.2",
+		name: "Muse Spark 1.2",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,
+		},
+		input: ["text", "image"],
+		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
+	{
+		id: "muse-spark-1.2-contributor",
+		name: "Muse Spark 1.2 Contributor",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,
+		},
+		input: ["text", "image"],
+		cost: { input: 0.1, output: 0.2, cacheRead: 0.002, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
+	{
+		id: "muse-spark-1.1",
+		name: "Muse Spark 1.1",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,
+		},
+		input: ["text", "image"],
+		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
+		contextWindow: 1_048_576,
+		maxTokens: 256_000,
+		compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+	},
+];
+
+function delay(milliseconds: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function responseBody(
+	response: Response,
+): Promise<Record<string, unknown>> {
+	const text = await response.text();
+	if (!text) return {};
+	try {
+		const value = JSON.parse(text) as unknown;
+		return value && typeof value === "object" && !Array.isArray(value)
+			? (value as Record<string, unknown>)
+			: {};
+	} catch {
+		return {};
+	}
+}
+
+function errorDetail(body: Record<string, unknown>): string | undefined {
+	for (const key of ["error_description", "detail", "message", "error"]) {
+		const value = body[key];
+		if (typeof value === "string" && value.trim()) return value.trim();
+	}
+	return undefined;
+}
+
+async function postForm<T>(
+	url: string,
+	fields: Record<string, string>,
+	fetchImpl: Fetch,
+): Promise<{ response: Response; body: T & Record<string, unknown> }> {
+	const response = await fetchImpl(url, {
+		method: "POST",
+		headers: {
+			Accept: "application/json",
+			"Content-Type": "application/x-www-form-urlencoded",
+		},
+		body: new URLSearchParams(fields),
+		redirect: "manual",
+	});
+	return {
+		response,
+		body: (await responseBody(response)) as T & Record<string, unknown>,
+	};
+}
+
+function isAbortSignal(value: unknown): value is AbortSignal {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"aborted" in value &&
+		typeof (value as AbortSignal).aborted === "boolean"
+	);
+}
+
+export async function mintMetaApiKey(
+	identityToken: string,
+	fetchImpl: Fetch = fetch,
+	signal?: AbortSignal,
+): Promise<string> {
+	const response = await fetchImpl(API_KEY_MINT_URL, {
+		method: "POST",
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${identityToken}`,
+			"Content-Type": "application/json",
+			"x-api-version": "1.0.0",
+		},
+		body: "{}",
+		signal,
+	});
+	const body = (await responseBody(response)) as MintResponse &
+		Record<string, unknown>;
+	if (!response.ok) {
+		const detail = errorDetail(body);
+		if (response.status === 401 || response.status === 403) {
+			throw new Error(
+				`Meta session expired (HTTP ${response.status}); run /login meta again${detail ? `: ${detail}` : ""}`,
+			);
+		}
+		throw new Error(
+			`Meta API-key mint failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}`,
+		);
+	}
+	if (typeof body.api_key !== "string" || !body.api_key) {
+		const setup =
+			typeof body.action_url === "string" && body.action_url
+				? ` Complete setup at ${body.action_url}.`
+				: "";
+		throw new Error(`Meta did not issue an API key.${setup}`);
+	}
+	return body.api_key;
+}
+
+/**
+ * API-key login: prompt for a Meta Model API key, validate it against the
+ * model catalog, and store it as a static credential. No daily re-minting —
+ * refreshMetaToken passes the key through unchanged.
+ */
+export async function loginMetaWithApiKey(
+	callbacks: OAuthLoginCallbacks,
+	fetchImpl: Fetch = fetch,
+): Promise<OAuthCredentials> {
+	const key = (
+		await callbacks.onPrompt({ message: "Meta Model API key:" })
+	).trim();
+	if (!key) throw new Error("Meta login requires an API key");
+	callbacks.onProgress?.("Validating Meta Model API key…");
+	const response = await fetchImpl(META_MODEL_CATALOG_URL, {
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${key}`,
+			"x-api-version": "1.0.0",
+		},
+	});
+	if (!response.ok) {
+		const detail = errorDetail(await responseBody(response));
+		if (response.status === 401 || response.status === 403) {
+			throw new Error(
+				`Meta rejected the API key (HTTP ${response.status})${detail ? `: ${detail}` : ""}`,
+			);
+		}
+		throw new Error(
+			`Meta API key validation failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}`,
+		);
+	}
+	return {
+		refresh: `${STATIC_API_KEY_PREFIX}${key}`,
+		access: key,
+		expires: Date.now() + API_KEY_REFRESH_INTERVAL_MS,
+	};
+}
+
+export async function loginMeta(
+	callbacks: OAuthLoginCallbacks,
+	fetchImpl: Fetch = fetch,
+	sleep: Sleep = delay,
+): Promise<OAuthCredentials> {
+	// Offer API-key login next to the device flow. Hosts without onSelect and
+	// dismissed selectors (undefined) keep the original device-flow behavior.
+	const method = await callbacks.onSelect?.({
+		message: "Select Meta login method:",
+		options: [
+			{ id: "browser", label: "Browser login (Meta device flow)" },
+			{ id: "api-key", label: "Paste a Model API key" },
+		],
+	});
+	if (method === "api-key") {
+		return loginMetaWithApiKey(callbacks, fetchImpl);
+	}
+	callbacks.onProgress?.("Starting Meta device authorization…");
+	const authorization = await postForm<DeviceAuthorization>(
+		DEVICE_AUTHORIZATION_URL,
+		{ client_id: META_CLIENT_ID },
+		fetchImpl,
+	);
+	if (!authorization.response.ok) {
+		throw new Error(
+			`Meta login could not be started (HTTP ${authorization.response.status})${errorDetail(authorization.body) ? `: ${errorDetail(authorization.body)}` : ""}`,
+		);
+	}
+	const device = authorization.body;
+	if (!device.device_code || !device.user_code || !device.verification_uri) {
+		throw new Error("Meta device authorization returned an incomplete response");
+	}
+
+	let intervalSeconds =
+		Number.isFinite(device.interval) && Number(device.interval) > 0
+			? Number(device.interval)
+			: 5;
+	const expiresInSeconds =
+		Number.isFinite(device.expires_in) && Number(device.expires_in) > 0
+			? Number(device.expires_in)
+			: 900;
+	const deadline = Date.now() + expiresInSeconds * 1000;
+	callbacks.onDeviceCode({
+		userCode: device.user_code,
+		verificationUri: device.verification_uri_complete || device.verification_uri,
+		intervalSeconds,
+		expiresInSeconds,
+	});
+	callbacks.onProgress?.("Waiting for Meta login approval…");
+
+	let identityToken: string | undefined;
+	while (Date.now() < deadline) {
+		await sleep(intervalSeconds * 1000);
+		const grant = await postForm<DeviceTokenGrant & OAuthError>(
+			DEVICE_TOKEN_URL,
+			{
+				grant_type: DEVICE_CODE_GRANT,
+				device_code: device.device_code,
+				client_id: META_CLIENT_ID,
+			},
+			fetchImpl,
+		);
+		if (grant.response.ok && grant.body.access_token) {
+			identityToken = grant.body.access_token;
+			break;
+		}
+		switch (grant.body.error) {
+			case "authorization_pending":
+				continue;
+			case "slow_down":
+				intervalSeconds += 5;
+				continue;
+			case "access_denied":
+				throw new Error("Meta login was denied");
+			case "expired_token":
+				throw new Error("Meta login request expired");
+			default:
+				throw new Error(
+					`Meta login failed (HTTP ${grant.response.status})${errorDetail(grant.body) ? `: ${errorDetail(grant.body)}` : ""}`,
+				);
+		}
+	}
+	if (!identityToken) throw new Error("Meta login request expired");
+
+	callbacks.onProgress?.("Enabling Meta Model API access…");
+	const apiKey = await mintMetaApiKey(identityToken, fetchImpl);
+	return {
+		refresh: identityToken,
+		access: apiKey,
+		expires: Date.now() + API_KEY_REFRESH_INTERVAL_MS,
+	};
+}
+
+export async function refreshMetaToken(
+	credentials: OAuthCredentials,
+	fetchOrSignal: Fetch | AbortSignal = fetch,
+): Promise<OAuthCredentials> {
+	if (credentials.refresh?.startsWith(STATIC_API_KEY_PREFIX)) {
+		// Static API-key login: nothing to re-mint; keep the key, roll expiry.
+		return {
+			...credentials,
+			access:
+				credentials.refresh.slice(STATIC_API_KEY_PREFIX.length) ||
+				credentials.access,
+			expires: Date.now() + API_KEY_REFRESH_INTERVAL_MS,
+		};
+	}
+	if (!credentials.refresh)
+		throw new Error(
+			"Meta login is missing its identity token; run /login meta again",
+		);
+	// Pi 0.83 calls refreshToken(credentials). Pi 0.84 passes AbortSignal as
+	// the second argument. Tests inject a fetch mock in that slot.
+	const fetchImpl = typeof fetchOrSignal === "function" ? fetchOrSignal : fetch;
+	const signal = isAbortSignal(fetchOrSignal) ? fetchOrSignal : undefined;
+	if (signal?.aborted) {
+		throw new Error("Meta token refresh was cancelled");
+	}
+	return {
+		...credentials,
+		access: await mintMetaApiKey(credentials.refresh, fetchImpl, signal),
+		expires: Date.now() + API_KEY_REFRESH_INTERVAL_MS,
+	};
+}
+
+function finitePositive(value: unknown, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? value
+		: fallback;
+}
+
+function numericCost(value: unknown, fallback: number): number {
+	const number =
+		typeof value === "number"
+			? value
+			: typeof value === "string" && value.trim()
+				? Number(value)
+				: Number.NaN;
+	return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+
+function displayName(id: string): string {
+	return id
+		.split("-")
+		.map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+		.join(" ");
+}
+
+function modalitiesToInput(
+	modalities: string[] | undefined,
+	fallback: MetaProviderModel["input"] | undefined,
+): MetaProviderModel["input"] {
+	if (!modalities) return fallback ?? ["text"];
+	const input: MetaProviderModel["input"] = ["text"];
+	if (modalities.includes("image")) input.push("image");
+	return input;
+}
+
+export function toProviderModels(
+	catalog: CatalogResponse,
+): MetaProviderModel[] {
+	return (catalog.data ?? []).flatMap((entry) => {
+		if (typeof entry.id !== "string" || !entry.id) return [];
+		const metadata = entry.metadata?.["muse-code"];
+		if (metadata?.is_hidden) return [];
+		const fallback = FALLBACK_MODELS.find((model) => model.id === entry.id);
+		const catalogName = metadata?.name === entry.id ? undefined : metadata?.name;
+		const variants = metadata?.variants ?? {};
+		const thinkingLevelMap: NonNullable<MetaProviderModel["thinkingLevelMap"]> = {
+			off: null,
+			minimal: variants.minimal?.reasoningEffort ?? "minimal",
+			low: variants.low?.reasoningEffort ?? "low",
+			medium: variants.medium?.reasoningEffort ?? "medium",
+			high: variants.high?.reasoningEffort ?? "high",
+			xhigh: variants.xhigh?.reasoningEffort ?? "xhigh",
+			max: variants.max?.reasoningEffort ?? fallback?.thinkingLevelMap?.max ?? null,
+		};
+		return [
+			{
+				id: entry.id,
+				name: catalogName || fallback?.name || displayName(entry.id),
+				reasoning: metadata?.reasoning ?? fallback?.reasoning ?? true,
+				thinkingLevelMap,
+				input: modalitiesToInput(metadata?.modalities?.input, fallback?.input),
+				cost: {
+					input: numericCost(metadata?.cost?.input, fallback?.cost.input ?? 0),
+					output: numericCost(metadata?.cost?.output, fallback?.cost.output ?? 0),
+					cacheRead: numericCost(
+						metadata?.cost?.cached,
+						fallback?.cost.cacheRead ?? 0,
+					),
+					cacheWrite: 0,
+				},
+				contextWindow: finitePositive(
+					metadata?.limit?.context,
+					fallback?.contextWindow ?? 1_048_576,
+				),
+				maxTokens: finitePositive(
+					metadata?.limit?.output,
+					fallback?.maxTokens ?? 256_000,
+				),
+				compat: { supportsReasoningEffort: true, supportsToolSearch: true },
+			} satisfies MetaProviderModel,
+		];
+	});
+}
+
+interface CatalogStore {
+	read(): Promise<ModelsStoreEntry | undefined>;
+	write(entry: ModelsStoreEntry): Promise<void>;
+}
+
+interface CompatibleRefreshContext {
+	credential?: RefreshModelsContext["credential"];
+	allowNetwork: boolean;
+	signal?: AbortSignal;
+	// Pi 0.83 catalog persistence API.
+	store?: CatalogStore;
+	// Pi 0.84 generation-checked catalog persistence API.
+	stored?: Readonly<ModelsStoreEntry>;
+	publish?(publication: { persist?: ModelsStoreEntry | null }): Promise<boolean>;
+}
+
+function providerModelsFromStore(
+	entry: Readonly<ModelsStoreEntry> | undefined,
+): MetaProviderModel[] {
+	return (entry?.models ?? []).flatMap((model: Model<Api>) => {
+		if (model.provider !== META_PROVIDER_ID || model.api !== "openai-responses")
+			return [];
+		return [
+			{
+				id: model.id,
+				name: model.name,
+				api: model.api,
+				baseUrl: model.baseUrl,
+				reasoning: model.reasoning,
+				thinkingLevelMap: model.thinkingLevelMap,
+				input: model.input as MetaProviderModel["input"],
+				cost: model.cost,
+				contextWindow: model.contextWindow,
+				maxTokens: model.maxTokens,
+				headers: model.headers,
+				compat: model.compat as MetaProviderModel["compat"],
+			},
+		];
+	});
+}
+
+function modelsForStore(
+	models: MetaProviderModel[],
+): Model<"openai-responses">[] {
+	return models.map((model) => ({
+		...model,
+		api: "openai-responses",
+		provider: META_PROVIDER_ID,
+		baseUrl: model.baseUrl ?? META_API_BASE_URL,
+		input: model.input as Model<"openai-responses">["input"],
+		compat: model.compat as Model<"openai-responses">["compat"],
+	}));
+}
+
+async function cachedMetaModels(
+	context: CompatibleRefreshContext,
+): Promise<MetaProviderModel[]> {
+	try {
+		const stored = context.stored ?? (await context.store?.read());
+		return providerModelsFromStore(stored);
+	} catch {
+		// Catalog persistence is best-effort; bundled fallbacks remain available.
+		return [];
+	}
+}
+
+async function persistMetaModels(
+	context: CompatibleRefreshContext,
+	entry: ModelsStoreEntry,
+): Promise<void> {
+	if (context.publish) {
+		await context.publish({ persist: entry });
+		return;
+	}
+	await context.store?.write(entry);
+}
+
+export async function refreshMetaModels(
+	context: RefreshModelsContext,
+	fetchImpl: Fetch = fetch,
+): Promise<MetaProviderModel[]> {
+	// SAFETY: CompatibleRefreshContext is the union of the Pi 0.83 and 0.84
+	// refresh-context fields that this adapter probes defensively at runtime.
+	const compatibleContext = context as unknown as CompatibleRefreshContext;
+	if (!context.allowNetwork || context.signal?.aborted) {
+		const cached = await cachedMetaModels(compatibleContext);
+		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+	}
+	const apiKey =
+		context.credential?.type === "oauth"
+			? context.credential.access
+			: context.credential?.type === "api_key"
+				? context.credential.key
+				: undefined;
+	if (!apiKey) {
+		const cached = await cachedMetaModels(compatibleContext);
+		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+	}
+
+	try {
+		const response = await fetchImpl(META_MODEL_CATALOG_URL, {
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${apiKey}`,
+				"x-api-version": "1.0.0",
+			},
+			signal: context.signal,
+		});
+		const body = (await responseBody(response)) as CatalogResponse &
+			Record<string, unknown>;
+		if (!response.ok) {
+			throw new Error(
+				`Meta model catalog failed (HTTP ${response.status})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`,
+			);
+		}
+		const models = toProviderModels(body);
+		if (models.length === 0) {
+			const cached = await cachedMetaModels(compatibleContext);
+			return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+		}
+		if (!context.signal?.aborted) {
+			try {
+				await persistMetaModels(compatibleContext, {
+					models: modelsForStore(models),
+					checkedAt: Date.now(),
+				});
+			} catch {
+				// Keep the fresh catalog usable even if persistence fails.
+			}
+		}
+		return models;
+	} catch (error) {
+		if (context.signal?.aborted) throw error;
+		const cached = await cachedMetaModels(compatibleContext);
+		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+	}
+}
+
+export function metaFallbackCost(
+	modelId: string,
+): MetaProviderModel["cost"] | undefined {
+	return FALLBACK_MODELS.find((model) => model.id === modelId)?.cost;
+}
+
+/** Meta prompt-cache opt-in. Measured 0% hits on /chat/completions vs 93–99% on /responses with 24h. */
+export const META_PROMPT_CACHE_RETENTION = "24h";
+
+const ENCRYPTED_REASONING_INCLUDE = "reasoning.encrypted_content";
+const PROBE_RETRY_MS = 5 * 60 * 1000;
+
+/**
+ * Keys minted through /muse-code/key are not always entitled to encrypted
+ * reasoning replay (Meta answers HTTP 400 "reasoning `encrypted_content`
+ * was not issued to this caller" when they aren't). Entitlement can change
+ * between minted keys, so probe once per key per process instead of
+ * hard-coding a decision: requests never 400 and reasoning continuity is
+ * kept whenever the key allows it.
+ */
+interface EntitlementCache {
+	keyHash?: string;
+	known?: boolean;
+	lastAttemptAt: number;
+}
+const entitlementCache: EntitlementCache = { lastAttemptAt: 0 };
+
+function apiKeyHash(key: string): string {
+	// Non-cryptographic FNV-1a; only used to key the in-process probe cache.
+	let hash = 2166136261;
+	for (let i = 0; i < key.length; i++) {
+		hash ^= key.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16);
+}
+
+/**
+ * Probe whether the given API key can request reasoning.encrypted_content.
+ * Returns true (200), false (Meta rejects the include), or undefined when
+ * the probe was inconclusive (transient error) and must be retried later.
+ */
+export async function probeEncryptedReasoningEntitlement(
+	apiKey: string,
+	fetchImpl: Fetch = fetch,
+): Promise<boolean | undefined> {
+	try {
+		const response = await fetchImpl(`${META_API_BASE_URL}/responses`, {
+			method: "POST",
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+				"x-api-version": "1.0.0",
+			},
+			body: JSON.stringify({
+				model: "muse-spark-1.3",
+				input: "Answer with the single letter: a",
+				include: [ENCRYPTED_REASONING_INCLUDE],
+				max_output_tokens: 16,
+				store: false,
+			}),
+		});
+		if (response.status === 200) return true;
+		if (response.status === 400) {
+			const text = await response.text();
+			if (text.includes("encrypted_content")) return false;
+		}
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function scheduleEntitlementProbe(apiKey: string): void {
+	const hash = apiKeyHash(apiKey);
+	if (
+		entitlementCache.keyHash === hash &&
+		entitlementCache.known !== undefined
+	) {
+		return;
+	}
+	if (Date.now() - entitlementCache.lastAttemptAt < PROBE_RETRY_MS) return;
+	entitlementCache.lastAttemptAt = Date.now();
+	void probeEncryptedReasoningEntitlement(apiKey).then((known) => {
+		if (known !== undefined) {
+			entitlementCache.keyHash = hash;
+			entitlementCache.known = known;
+		}
+	});
+}
+
+function keepEncryptedReasoningFor(apiKey: string | undefined): boolean {
+	if (!apiKey) return false;
+	if (entitlementCache.keyHash !== apiKeyHash(apiKey)) return false;
+	return entitlementCache.known === true;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+/**
+ * Hermes-equivalent Responses hints for api.meta.ai:
+ * setdefault `prompt_cache_retention: 24h`, and drop `reasoning.effort: none`
+ * because Meta 400s on it.
+ */
+export function applyMetaResponsesCacheHints(
+	payload: unknown,
+	keepEncryptedReasoning = false,
+): Record<string, unknown> | undefined {
+	const body = asRecord(payload);
+	if (!body) return undefined;
+	if (body.prompt_cache_retention === undefined) {
+		body.prompt_cache_retention = META_PROMPT_CACHE_RETENTION;
+	}
+	// Drop the encrypted-reasoning include unless the key was probed and
+	// found entitled: unentitled keys get a fatal HTTP 400 for it (see
+	// probeEncryptedReasoningEntitlement). Other include entries survive.
+	if (!keepEncryptedReasoning && Array.isArray(body.include)) {
+		const include = body.include.filter(
+			(item) => item !== "reasoning.encrypted_content",
+		);
+		if (include.length === 0) delete body.include;
+		else body.include = include;
+	}
+	const reasoning = asRecord(body.reasoning);
+	if (
+		reasoning &&
+		(reasoning.effort === "none" ||
+			reasoning.effort === undefined ||
+			reasoning.effort === null)
+	) {
+		delete body.reasoning;
+	}
+	return body;
+}
+
+export function createMetaProviderConfig(): ProviderConfig {
+	return {
+		name: "Meta Model API",
+		baseUrl: META_API_BASE_URL,
+		api: "openai-responses",
+		apiKey: "$META_API_KEY",
+		models: [...FALLBACK_MODELS],
+		refreshModels: refreshMetaModels,
+		oauth: {
+			name: "Meta Model API (browser login or API key)",
+			login: loginMeta,
+			refreshToken: refreshMetaToken,
+			getApiKey: (credentials: { access: string }) => credentials.access,
+		},
+	};
+}
+
+export default function metaOAuthProvider(pi: ExtensionAPI): void {
+	// Allow MODEL_API_KEY as fallback for API-key users — shim to META_API_KEY so $META_API_KEY interpolation works.
+	if (
+		process.env[META_ENV_VAR] === undefined &&
+		process.env["MODEL_API_KEY"] !== undefined
+	) {
+		process.env[META_ENV_VAR] = process.env["MODEL_API_KEY"];
+	}
+	if (
+		process.env["MODEL_API_KEY"] === undefined &&
+		process.env[META_ENV_VAR] !== undefined
+	) {
+		process.env["MODEL_API_KEY"] = process.env[META_ENV_VAR];
+	}
+	pi.registerProvider(META_PROVIDER_ID, createMetaProviderConfig());
+	pi.on("before_provider_request", async (event, ctx) => {
+		if (ctx.model?.provider !== META_PROVIDER_ID) return undefined;
+		let apiKey: string | undefined;
+		try {
+			apiKey = (await ctx.modelRegistry?.getProviderAuth(META_PROVIDER_ID))
+				?.auth?.apiKey;
+		} catch {
+			apiKey = undefined;
+		}
+		if (apiKey) scheduleEntitlementProbe(apiKey);
+		return applyMetaResponsesCacheHints(
+			event.payload,
+			keepEncryptedReasoningFor(apiKey),
+		);
+	});
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@geocine/pi-meta-oauth",
+  "version": "0.6.1",
+  "description": "Meta Model API OAuth provider for pi",
+  "keywords": [
+    "pi-package",
+    "meta",
+    "muse-spark",
+    "oauth",
+    "provider"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "extensions/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BlockedPath/pi-meta-oauth"
+  },
+  "homepage": "https://github.com/BlockedPath/pi-meta-oauth#readme",
+  "bugs": {
+    "url": "https://github.com/BlockedPath/pi-meta-oauth/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/meta.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/BlockedPath/pi-meta-oauth/main/preview.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.83.0 <0.86.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <0.86.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "bun-types": "latest",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}