pi-meta-oauth 0.7.0 → 0.7.2

package/src/meta/muse-policy.ts

@@ -0,0 +1,32 @@
+import { MUSE_USER_AGENT_ENV_VAR } from "./constants.ts";
+import type { MetaEnv, MetaProviderModel } from "./types.ts";
+
+/** Models whose max effort requires the captured Muse client fingerprint. */
+export const MUSE_USER_AGENT_MODEL_IDS: ReadonlySet<string> = new Set([
+	"muse-spark-1.3-contributor",
+]);
+
+/** Recognize the documented, explicit Muse fingerprint opt-in values. */
+export function isMuseUserAgentEnabled(env: MetaEnv = process.env): boolean {
+	const configured = env[MUSE_USER_AGENT_ENV_VAR];
+	if (typeof configured !== "string") return false;
+	const value = configured.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "yes";
+}
+
+/**
+ * Gate the literal max effort on known fingerprint-dependent models. A future
+ * server-advertised mapping to a different effort remains authoritative.
+ */
+export function gateMuseMaxEffort(
+	model: MetaProviderModel,
+	env: MetaEnv = process.env,
+): MetaProviderModel {
+	const map = model.thinkingLevelMap;
+	if (!map || !MUSE_USER_AGENT_MODEL_IDS.has(model.id)) return model;
+	if (map.max != null && map.max !== "max") return model;
+
+	const max = isMuseUserAgentEnabled(env) ? "max" : null;
+	if (map.max === max) return model;
+	return { ...model, thinkingLevelMap: { ...map, max } };
+}

package/src/meta/oauth.ts

@@ -0,0 +1,382 @@
+import type {
+	OAuthCredentials,
+	OAuthLoginCallbacks,
+} from "@earendil-works/pi-ai";
+import {
+	API_KEY_MINT_URL,
+	API_KEY_REFRESH_INTERVAL_MS,
+	DEVICE_AUTHORIZATION_URL,
+	DEVICE_CODE_GRANT,
+	DEVICE_TOKEN_URL,
+	META_API_VERSION,
+	META_CLIENT_ID,
+	META_REQUEST_TIMEOUT_MS,
+} from "./constants.ts";
+import {
+	asRecord,
+	delay,
+	errorDetail,
+	postForm,
+	RequestTimeoutError,
+	responseBody,
+	withRequestTimeout,
+} from "./http.ts";
+import type { Fetch, Sleep } from "./types.ts";
+
+type Clock = () => number;
+
+interface DeviceAuthorization {
+	deviceCode: string;
+	userCode: string;
+	verificationUri: string;
+	intervalSeconds: number;
+	expiresInSeconds: number;
+}
+
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_DEVICE_EXPIRY_SECONDS = 900;
+const POLL_SLOW_DOWN_SECONDS = 5;
+/** Never poll faster than this, matching Pi's built-in device-code poller. */
+const MIN_POLL_INTERVAL_SECONDS = 1;
+/**
+ * Pi's interactive login hides a failure only when its message is exactly this
+ * string (as its built-in OAuth flows throw), so a user cancel stays silent.
+ */
+const LOGIN_CANCELLED_MESSAGE = "Login cancelled";
+
+function isNonBlankString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function positiveSeconds(value: unknown, fallback: number): number {
+	return typeof value === "number" &&
+		Number.isFinite(value) &&
+		value > 0 &&
+		Number.isFinite(value * 1000)
+		? value
+		: fallback;
+}
+
+/**
+ * Pi writes server-supplied URLs to the terminal, the device URI as a clickable
+ * link. Mirror its built-in Meta flow: http(s) only, re-serialized through
+ * URL so control characters arrive percent-encoded.
+ */
+function trustedHttpUrl(value: unknown): string | undefined {
+	if (!isNonBlankString(value)) return undefined;
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" || url.protocol === "http:"
+			? url.href
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function failure(message: string, body: Record<string, unknown>): Error {
+	const detail = errorDetail(body);
+	return new Error(`${message}${detail ? `: ${detail}` : ""}`);
+}
+
+/** Say which request timed out; every other failure passes through. */
+function timeoutAs(message: string): (error: unknown) => never {
+	return (error) => {
+		if (error instanceof RequestTimeoutError) {
+			throw new Error(message, { cause: error });
+		}
+		throw error;
+	};
+}
+
+function checkLoginCancellation(signal?: AbortSignal): void {
+	if (signal?.aborted) throw new Error(LOGIN_CANCELLED_MESSAGE);
+}
+
+function waitForPoll(
+	milliseconds: number,
+	sleep: Sleep,
+	signal?: AbortSignal,
+): Promise<void> {
+	checkLoginCancellation(signal);
+	if (!signal) return sleep(milliseconds);
+
+	return new Promise((resolve, reject) => {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const cleanup = () => {
+			signal.removeEventListener("abort", onAbort);
+			if (timer !== undefined) clearTimeout(timer);
+		};
+		const complete = () => {
+			cleanup();
+			resolve();
+		};
+		const fail = (error: unknown) => {
+			cleanup();
+			reject(error);
+		};
+		const onAbort = () => fail(new Error(LOGIN_CANCELLED_MESSAGE));
+		signal.addEventListener("abort", onAbort, { once: true });
+		if (signal.aborted) {
+			onAbort();
+			return;
+		}
+		// Own the default timer so cancellation also clears its pending work.
+		if (sleep === delay) {
+			timer = setTimeout(complete, milliseconds);
+			return;
+		}
+		try {
+			// Keep both handlers attached if an injected sleep finishes after abort.
+			sleep(milliseconds).then(complete, fail);
+		} catch (error) {
+			fail(error);
+		}
+	});
+}
+
+async function requestDeviceAuthorization(
+	fetchImpl: Fetch,
+	signal?: AbortSignal,
+): Promise<DeviceAuthorization> {
+	checkLoginCancellation(signal);
+	const { response, body } = await postForm(
+		DEVICE_AUTHORIZATION_URL,
+		{ client_id: META_CLIENT_ID },
+		fetchImpl,
+		signal,
+	).catch(timeoutAs("Meta login request timed out"));
+	checkLoginCancellation(signal);
+	if (!response.ok) {
+		throw failure(
+			`Meta login could not be started (HTTP ${response.status})`,
+			body,
+		);
+	}
+	const verificationUri =
+		trustedHttpUrl(body.verification_uri_complete) ??
+		trustedHttpUrl(body.verification_uri);
+	if (
+		!isNonBlankString(body.device_code) ||
+		!isNonBlankString(body.user_code) ||
+		verificationUri === undefined
+	) {
+		throw new Error(
+			"Meta device authorization returned an incomplete response",
+		);
+	}
+
+	return {
+		deviceCode: body.device_code,
+		userCode: body.user_code,
+		verificationUri,
+		intervalSeconds: positiveSeconds(
+			body.interval,
+			DEFAULT_POLL_INTERVAL_SECONDS,
+		),
+		expiresInSeconds: positiveSeconds(
+			body.expires_in,
+			DEFAULT_DEVICE_EXPIRY_SECONDS,
+		),
+	};
+}
+
+async function pollIdentityToken(
+	device: DeviceAuthorization,
+	deadline: number,
+	fetchImpl: Fetch,
+	sleep: Sleep,
+	now: Clock,
+	signal?: AbortSignal,
+): Promise<string> {
+	let intervalSeconds = Math.max(
+		MIN_POLL_INTERVAL_SECONDS,
+		device.intervalSeconds,
+	);
+	while (true) {
+		checkLoginCancellation(signal);
+		const remainingMilliseconds = deadline - now();
+		if (remainingMilliseconds <= 0) break;
+		await waitForPoll(
+			Math.min(intervalSeconds * 1000, remainingMilliseconds),
+			sleep,
+			signal,
+		);
+		checkLoginCancellation(signal);
+		// A device code can expire while waiting, especially after slow_down.
+		const pollMilliseconds = deadline - now();
+		if (pollMilliseconds <= 0) break;
+
+		// Cap a stalled poll at the deadline, where its timeout means expiry.
+		const expiresFirst = pollMilliseconds <= META_REQUEST_TIMEOUT_MS;
+		const { response, body } = await postForm(
+			DEVICE_TOKEN_URL,
+			{
+				grant_type: DEVICE_CODE_GRANT,
+				device_code: device.deviceCode,
+				client_id: META_CLIENT_ID,
+			},
+			fetchImpl,
+			signal,
+			expiresFirst ? Math.max(1, pollMilliseconds) : META_REQUEST_TIMEOUT_MS,
+		).catch(
+			timeoutAs(
+				expiresFirst
+					? "Meta login request expired"
+					: "Meta login request timed out",
+			),
+		);
+		checkLoginCancellation(signal);
+		if (response.ok && isNonBlankString(body.access_token)) {
+			return body.access_token;
+		}
+		switch (body.error) {
+			case "authorization_pending":
+				break;
+			case "slow_down":
+				// RFC 8628 §3.5 adds five seconds; a longer server-supplied interval wins.
+				intervalSeconds = Math.max(
+					intervalSeconds + POLL_SLOW_DOWN_SECONDS,
+					positiveSeconds(body.interval, 0),
+				);
+				break;
+			case "access_denied":
+				throw new Error("Meta login was denied");
+			case "expired_token":
+				throw new Error("Meta login request expired");
+			default:
+				throw failure(`Meta login failed (HTTP ${response.status})`, body);
+		}
+	}
+	throw new Error("Meta login request expired");
+}
+
+export async function mintMetaApiKey(
+	identityToken: string,
+	fetchImpl: Fetch = globalThis.fetch,
+	signal?: AbortSignal,
+	timeoutMs = META_REQUEST_TIMEOUT_MS,
+): Promise<string> {
+	signal?.throwIfAborted();
+	const { response, body } = await withRequestTimeout(
+		signal,
+		timeoutMs,
+		async (requestSignal) => {
+			const response = await fetchImpl(API_KEY_MINT_URL, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${identityToken}`,
+					"Content-Type": "application/json",
+					"x-api-version": META_API_VERSION,
+				},
+				body: "{}",
+				signal: requestSignal,
+			});
+			return { response, body: await responseBody(response) };
+		},
+	).catch(timeoutAs("Meta API-key mint timed out"));
+	signal?.throwIfAborted();
+	if (!response.ok) {
+		const message =
+			response.status === 401 || response.status === 403
+				? `Meta session expired (HTTP ${response.status}); run /login meta again`
+				: `Meta API-key mint failed (HTTP ${response.status})`;
+		throw failure(message, body);
+	}
+	if (!isNonBlankString(body.api_key)) {
+		const actionUrl = trustedHttpUrl(body.action_url);
+		const setup = actionUrl ? ` Complete setup at ${actionUrl}.` : "";
+		throw new Error(`Meta did not issue an API key.${setup}`);
+	}
+	return body.api_key;
+}
+
+export async function loginMeta(
+	callbacks: OAuthLoginCallbacks,
+	fetchImpl: Fetch = globalThis.fetch,
+	sleep: Sleep = delay,
+	now: Clock = Date.now,
+): Promise<OAuthCredentials> {
+	// Older Pi callbacks omit signal; its optional structural shape is compatible.
+	const compatibleCallbacks: OAuthLoginCallbacks & { signal?: AbortSignal } =
+		callbacks;
+	const { signal } = compatibleCallbacks;
+	try {
+		checkLoginCancellation(signal);
+		callbacks.onProgress?.("Starting Meta device authorization…");
+		const device = await requestDeviceAuthorization(fetchImpl, signal);
+		const deadline = now() + device.expiresInSeconds * 1000;
+		callbacks.onDeviceCode({
+			userCode: device.userCode,
+			verificationUri: device.verificationUri,
+			intervalSeconds: device.intervalSeconds,
+			expiresInSeconds: device.expiresInSeconds,
+		});
+		callbacks.onProgress?.("Waiting for Meta login approval…");
+		const identityToken = await pollIdentityToken(
+			device,
+			deadline,
+			fetchImpl,
+			sleep,
+			now,
+			signal,
+		);
+
+		checkLoginCancellation(signal);
+		callbacks.onProgress?.("Enabling Meta Model API access…");
+		const apiKey = await mintMetaApiKey(identityToken, fetchImpl, signal);
+		checkLoginCancellation(signal);
+		return {
+			refresh: identityToken,
+			access: apiKey,
+			expires: now() + API_KEY_REFRESH_INTERVAL_MS,
+		};
+	} catch (error) {
+		if (signal?.aborted) {
+			throw new Error(LOGIN_CANCELLED_MESSAGE, { cause: error });
+		}
+		throw error;
+	}
+}
+
+/** Pi 0.84+ also aborts refresh on its own timeout, which is not a cancel. */
+function refreshAborted(signal: AbortSignal, options?: ErrorOptions): Error {
+	return new Error(
+		asRecord(signal.reason)?.name === "TimeoutError"
+			? "Meta token refresh timed out"
+			: "Meta token refresh was cancelled",
+		options,
+	);
+}
+
+export async function refreshMetaToken(
+	credentials: OAuthCredentials,
+	fetchOrSignal: Fetch | AbortSignal = globalThis.fetch,
+): Promise<OAuthCredentials> {
+	if (!isNonBlankString(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 supplies an AbortSignal.
+	// The fetch injection in the same slot keeps the public helper testable.
+	const fetchImpl =
+		typeof fetchOrSignal === "function" ? fetchOrSignal : globalThis.fetch;
+	const signal =
+		typeof fetchOrSignal === "function" ? undefined : fetchOrSignal;
+	if (signal?.aborted) throw refreshAborted(signal);
+	let apiKey: string;
+	try {
+		apiKey = await mintMetaApiKey(credentials.refresh, fetchImpl, signal);
+	} catch (error) {
+		if (signal?.aborted) throw refreshAborted(signal, { cause: error });
+		throw error;
+	}
+	if (signal?.aborted) throw refreshAborted(signal);
+	return {
+		...credentials,
+		access: apiKey,
+		expires: Date.now() + API_KEY_REFRESH_INTERVAL_MS,
+	};
+}

package/src/meta/provider.ts

@@ -0,0 +1,53 @@
+// Pi's extension loader maps only pi-ai's root, compat, oauth, and providers
+// entrypoints; installed extensions cannot resolve `pi-ai/api/*` subpaths.
+import { openAIResponsesApi } from "@earendil-works/pi-ai/compat";
+import {
+	META_API_BASE_URL,
+	META_ENV_VAR,
+	META_PROVIDER_ID,
+} from "./constants.ts";
+import { refreshMetaModels } from "./model-store.ts";
+import { fallbackModels } from "./models.ts";
+import { loginMeta, refreshMetaToken } from "./oauth.ts";
+import {
+	applyMetaModelHeaders,
+	applyMetaResponsesCacheHints,
+} from "./request-policy.ts";
+import type { MetaProviderConfig } from "./types.ts";
+
+const { streamSimple } = openAIResponsesApi();
+
+export function createMetaProviderConfig(): MetaProviderConfig {
+	return {
+		name: "Meta Model API",
+		baseUrl: META_API_BASE_URL,
+		api: "openai-responses",
+		apiKey: `$${META_ENV_VAR}`,
+		streamSimple(model, context, options) {
+			// Pi's global hooks see the session selection, not the in-flight model.
+			// This adapter runs after auth/header resolution with the request's endpoint.
+			const requestModel = { ...model, api: "openai-responses" as const };
+			const headers = { ...model.headers, ...options?.headers };
+			applyMetaModelHeaders(headers, requestModel);
+			return streamSimple(requestModel, context, {
+				...options,
+				headers,
+				onPayload: async (payload, sentModel) => {
+					const replacement = await options?.onPayload?.(payload, sentModel);
+					const body = replacement === undefined ? payload : replacement;
+					return model.provider === META_PROVIDER_ID
+						? (applyMetaResponsesCacheHints(body) ?? body)
+						: body;
+				},
+			});
+		},
+		models: fallbackModels(),
+		refreshModels: refreshMetaModels,
+		oauth: {
+			name: "Meta Model API (browser login)",
+			login: loginMeta,
+			refreshToken: refreshMetaToken,
+			getApiKey: (credentials) => credentials.access,
+		},
+	};
+}

package/src/meta/request-policy.ts

@@ -0,0 +1,96 @@
+import {
+	META_PROMPT_CACHE_RETENTION,
+	META_PROVIDER_ID,
+	MUSE_USER_AGENT,
+} from "./constants.ts";
+import { asRecord } from "./http.ts";
+import {
+	isMuseUserAgentEnabled,
+	MUSE_USER_AGENT_MODEL_IDS,
+} from "./muse-policy.ts";
+import type { MetaEnv } from "./types.ts";
+
+type ProviderHeaders = Record<string, string | null>;
+
+/**
+ * Match the direct HTTPS Meta /v1 endpoint, allowing URL-normalized equivalent
+ * hostnames, the default port, and trailing slashes. Other hosts, paths, schemes,
+ * and ports never receive the Muse client fingerprint.
+ */
+export function isDirectMetaModelApiUrl(baseUrl: unknown): boolean {
+	if (typeof baseUrl !== "string" || !baseUrl) return false;
+	// URL.search/hash omit empty delimiters, which still break path appending.
+	if (baseUrl.includes("?") || baseUrl.includes("#")) return false;
+	try {
+		const parsed = new URL(baseUrl);
+		return (
+			parsed.protocol === "https:" &&
+			parsed.hostname.toLowerCase() === "api.meta.ai" &&
+			parsed.port === "" &&
+			parsed.username === "" &&
+			parsed.password === "" &&
+			parsed.pathname.replace(/\/+$/, "") === "/v1"
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Set the fingerprint only on direct endpoints without an explicit User-Agent.
+ * Header names are case-insensitive; null is an explicit suppression and wins.
+ * The caller owns provider, model, and opt-in checks; use applyMetaModelHeaders
+ * when handling provider events.
+ */
+export function applyMetaUserAgentFingerprint(
+	headers: ProviderHeaders,
+	baseUrl: unknown,
+): boolean {
+	if (!isDirectMetaModelApiUrl(baseUrl) || !asRecord(headers)) return false;
+	if (
+		Object.keys(headers).some((name) => name.toLowerCase() === "user-agent")
+	) {
+		return false;
+	}
+	headers["User-Agent"] = MUSE_USER_AGENT;
+	return true;
+}
+
+/** Apply every fingerprint guard in one place for the provider headers hook. */
+export function applyMetaModelHeaders(
+	headers: ProviderHeaders,
+	model: unknown,
+	env: MetaEnv = process.env,
+): boolean {
+	const requestModel = asRecord(model);
+	if (
+		requestModel?.provider !== META_PROVIDER_ID ||
+		typeof requestModel.id !== "string" ||
+		!MUSE_USER_AGENT_MODEL_IDS.has(requestModel.id) ||
+		!isMuseUserAgentEnabled(env)
+	) {
+		return false;
+	}
+	return applyMetaUserAgentFingerprint(headers, requestModel.baseUrl);
+}
+
+/** Set the Responses cache default and remove unsupported empty/none reasoning. */
+export function applyMetaResponsesCacheHints(
+	payload: unknown,
+): 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;
+	}
+	const reasoning = asRecord(body.reasoning);
+	if (
+		reasoning &&
+		(reasoning.effort === "none" ||
+			reasoning.effort === undefined ||
+			reasoning.effort === null)
+	) {
+		delete body.reasoning;
+	}
+	return body;
+}

package/src/meta/types.ts

@@ -0,0 +1,33 @@
+import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
+
+type ProviderModel = NonNullable<ProviderConfig["models"]>[number];
+
+/** Responses hints spanning the supported Pi versions, including newer flags. */
+export interface MetaResponsesCompat {
+	supportsReasoningEffort?: boolean;
+	supportsToolSearch?: boolean;
+	supportsDeveloperRole?: boolean;
+	supportsMidConvoSystemMessages?: boolean;
+	supportsLongCacheRetention?: boolean;
+	supportsStrictMode?: boolean;
+	supportsOpenAIGrammarTools?: boolean;
+	supportsAdditionalTools?: boolean;
+	supportsExplicitPromptCacheMode?: boolean;
+	supportsMaxOutputTokens?: boolean;
+	sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
+}
+
+/** This provider never registers metadata for another transport API. */
+export type MetaProviderModel = Omit<ProviderModel, "api" | "compat"> & {
+	api?: "openai-responses";
+	compat?: MetaResponsesCompat;
+};
+export type MetaProviderConfig = Omit<ProviderConfig, "models"> & {
+	models: MetaProviderModel[];
+};
+export type MetaEnv = Record<string, string | undefined>;
+/** Depend on fetch's callable contract, without runtime-specific static helpers. */
+export type Fetch = (
+	...args: Parameters<typeof globalThis.fetch>
+) => ReturnType<typeof globalThis.fetch>;
+export type Sleep = (milliseconds: number) => Promise<void>;