pi-meta-oauth 0.6.0 → 0.7.0

package/README.md

@@ -10,6 +10,7 @@ Meta Model API OAuth for [pi](https://pi.dev).
 
 - Use Muse Spark models through Pi's `openai-responses` provider (not `/chat/completions` — Muse prompt cache is ~0% there)
 - Send `prompt_cache_retention: "24h"` on Meta Responses requests unless the payload already set a retention
+- Optional, off by default: send the Muse CLI `User-Agent` on direct `muse-spark-1.3-contributor` requests so it accepts reasoning effort `max` (see [Contributor `max`](#contributor-max-opt-in))
 - Device authorization against `https://auth.meta.com`
 - Model API-key minting through `POST https://api.meta.ai/muse-code/key`
 - Dynamic Muse model catalog from `GET https://api.meta.ai/v1/models`
@@ -40,9 +41,12 @@ Pi displays a device code, opens the Meta authorization flow, and mints a Model
 
 The access key is re-minted daily.
 
+Prefer a static key instead? Set `META_API_KEY` (or `MODEL_API_KEY`) and skip
+`/login meta` entirely — requests use it directly.
+
 ## Models
 
-Fallback models use a 1,048,576-token context window, up to 256K output tokens, image input, and reasoning levels `minimal`, `low`, `medium`, `high`, and `xhigh`.
+Fallback models use a 1,048,576-token context window, up to 256K output tokens, image input, and reasoning levels `minimal`, `low`, `medium`, `high`, and `xhigh` (`muse-spark-1.3` additionally supports `max`; `muse-spark-1.3-contributor` does too when [opted in](#contributor-max-opt-in)).
 
 | id | pricing (input/output/cached) $/M |
 | --- | --- |
@@ -54,6 +58,25 @@ Fallback models use a 1,048,576-token context window, up to 256K output tokens,
 
 > **Contributor-model privacy:** discounted contributor models allow Meta to use prompts and completions for product improvement, including training future Meta models. Use a standard model such as `muse-spark-1.3` if you do not want the contributor terms. See [Meta's model documentation](https://dev.meta.ai/docs/models).
 
+### Contributor `max` (opt-in)
+
+Meta documents reasoning effort `max` for standard-tier `muse-spark-1.3` only. `muse-spark-1.3-contributor` rejects it (HTTP 400) unless the request carries the Muse CLI's `User-Agent` (observed 2026-09-25, same for API-key and `/login meta` credentials). To use it anyway, set `META_MUSE_USER_AGENT=1` (`true` and `yes` also work) in the environment Pi starts from:
+
+| OS / shell | Enable permanently |
+| --- | --- |
+| macOS (zsh, the default) | `echo 'export META_MUSE_USER_AGENT=1' >> ~/.zshrc` |
+| Linux (bash) | `echo 'export META_MUSE_USER_AGENT=1' >> ~/.bashrc` |
+| fish (any OS) | `set -Ux META_MUSE_USER_AGENT 1` |
+| Windows (PowerShell) | `[Environment]::SetEnvironmentVariable("META_MUSE_USER_AGENT", "1", "User")` |
+
+Then open a **new** terminal and restart Pi. Shells that were already open don't see the change, and long-running terminal apps or multiplexers (e.g. tmux) may need a full restart. On macOS/Linux you can instead run `source ~/.zshrc` (or `~/.bashrc`) in the current shell. For a single run, use `META_MUSE_USER_AGENT=1 pi`. To disable it, remove the line (fish: `set -Ue META_MUSE_USER_AGENT`; Windows: pass `$null` instead of `"1"`) and restart Pi.
+
+The header is the same on every OS. The captured string names `linux-x86_64`, but the platform segment doesn't appear to be checked: it was accepted from Windows (2026-09-26), and oh-my-pi sends the same fixed string on every platform.
+
+With the flag set, the extension exposes `max` on `muse-spark-1.3-contributor` and sends the captured Muse `User-Agent` on that model's requests to `https://api.meta.ai/v1` only. Other models, proxies and custom `baseUrl`s, and any `User-Agent` you set yourself are left untouched. Without the flag, Contributor `max` is hidden and Pi's own `User-Agent` is sent.
+
+> **Warning:** this makes Pi identify as Meta's first-party Muse client. It relies on undocumented server behavior, is not supported by Meta, may stop working without notice, and may conflict with Meta's terms. Enable it only if you accept that risk for your account.
+
 To scope Pi's model picker to Meta models:
 
 ```json
@@ -88,7 +111,7 @@ bun run typecheck
 bun test
 ```
 
-`bun test` is hermetic unless a Meta credential is already available. The live cache-hit probe makes real billable API calls when a credential resolves: two identical `/v1/responses` calls (asserting `cached_tokens` on the second), plus one 2s retry if that second call misses cache. The credential is resolved, in order, from `PI_META_LIVE_API_KEY`, `META_API_KEY`, `MODEL_API_KEY`, or the minted key from `~/.pi/agent/auth.json` after `/login meta` (skipped if expired). OAuth is enough — you do not need a separate key. Skipped when no valid credential exists (CI):
+`bun test` is hermetic unless a Meta credential is already available. The live cache-hit probe makes real billable API calls when a credential resolves: two identical `/v1/responses` calls (asserting `cached_tokens` on the second), plus one 2s retry if that second call misses cache. The live fingerprint probe makes two tiny Contributor-`max` calls: one without the fingerprint (status logged only) and one with it (asserting HTTP 200). It sends the header directly and does not depend on `META_MUSE_USER_AGENT`. The credential is resolved, in order, from `PI_META_LIVE_API_KEY`, `META_API_KEY`, `MODEL_API_KEY`, or the minted key from `~/.pi/agent/auth.json` after `/login meta` (skipped if expired). OAuth is enough — you do not need a separate key. Skipped when no valid credential exists (CI):
 
 ```bash
 bun test tests/meta-cache.test.ts

package/extensions/meta.ts

@@ -16,6 +16,29 @@ 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";
+/**
+ * User-Agent captured from the Muse CLI inference entrypoint, kept
+ * byte-for-byte (including the linux-x86_64 platform) because it is a
+ * captured fingerprint: variants for other platforms are unverified.
+ *
+ * Sending it on direct Meta Model API requests enables `reasoning.effort:
+ * "max"` on muse-spark-1.3-contributor (live-verified 2026-09-25 on
+ * login-minted credentials: identical payloads 400 without it and 200
+ * with it; API-key parity reported in oh-my-pi#12199). Observed wire
+ * behavior, not a permission claim: Meta documents `max` for standard-tier
+ * 1.3 only, and the gate may change server-side without notice.
+ *
+ * Off by default. It impersonates Meta's first-party client, so users opt
+ * in with {@link MUSE_USER_AGENT_ENV_VAR}; see {@link isMuseUserAgentEnabled}.
+ */
+export const MUSE_USER_AGENT =
+	"muse-build/1.3.0 (non-interactive; linux-x86_64; build ac7280f2aca67769d1455a8847bb502b617d50f6)";
+/** Set to `1`/`true`/`yes` to send {@link MUSE_USER_AGENT} and expose Contributor `max`. */
+export const MUSE_USER_AGENT_ENV_VAR = "META_MUSE_USER_AGENT";
+/** Models whose `max` effort Meta accepts only with the Muse fingerprint. */
+const MUSE_USER_AGENT_MODEL_IDS: ReadonlySet<string> = new Set([
+	"muse-spark-1.3-contributor",
+]);
 const META_ENV_VAR = "META_API_KEY";
 
 const DEVICE_AUTHORIZATION_URL = `${META_AUTH_BASE_URL}/oidc/device/authorization/`;
@@ -88,7 +111,7 @@ const FALLBACK_MODELS: MetaProviderModel[] = [
 			medium: "medium",
 			high: "high",
 			xhigh: "xhigh",
-			max: null,
+			max: "max",
 		},
 		input: ["text", "image"],
 		cost: { input: 1.25, output: 4.25, cacheRead: 0.15, cacheWrite: 0 },
@@ -107,6 +130,9 @@ const FALLBACK_MODELS: MetaProviderModel[] = [
 			medium: "medium",
 			high: "high",
 			xhigh: "xhigh",
+			// Accepted only with the Muse User-Agent fingerprint (live-verified
+			// 2026-09-25). gateMuseMaxEffort() maps this to "max" when
+			// META_MUSE_USER_AGENT opts in; otherwise it stays unexposed.
 			max: null,
 		},
 		input: ["text", "image"],
@@ -174,6 +200,37 @@ const FALLBACK_MODELS: MetaProviderModel[] = [
 	},
 ];
 
+type MetaEnv = Record<string, string | undefined>;
+
+/** True when the user opted in to the Muse User-Agent fingerprint. */
+export function isMuseUserAgentEnabled(env: MetaEnv = process.env): boolean {
+	const value = env[MUSE_USER_AGENT_ENV_VAR]?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "yes";
+}
+
+/**
+ * Expose `max` on fingerprint-gated models only when the fingerprint is
+ * enabled, so users who have not opted in are never offered a level that
+ * 400s. Any other explicit `max` mapping (e.g. a future server-advertised
+ * effort name) passes through unchanged.
+ */
+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;
+	return {
+		...model,
+		thinkingLevelMap: { ...map, max: isMuseUserAgentEnabled(env) ? "max" : null },
+	};
+}
+
+function fallbackModels(): MetaProviderModel[] {
+	return FALLBACK_MODELS.map((model) => gateMuseMaxEffort(model));
+}
+
 function delay(milliseconds: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
@@ -249,8 +306,14 @@ export async function mintMetaApiKey(
 	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})${errorDetail(body) ? `: ${errorDetail(body)}` : ""}`,
+			`Meta API-key mint failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}`,
 		);
 	}
 	if (typeof body.api_key !== "string" || !body.api_key) {
@@ -406,7 +469,8 @@ export function toProviderModels(
 		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);
+		// Gated fallbacks: a server-advertised variants.max still wins below.
+		const fallback = fallbackModels().find((model) => model.id === entry.id);
 		const catalogName = metadata?.name === entry.id ? undefined : metadata?.name;
 		const variants = metadata?.variants ?? {};
 		const thinkingLevelMap: NonNullable<MetaProviderModel["thinkingLevelMap"]> = {
@@ -416,7 +480,7 @@ export function toProviderModels(
 			medium: variants.medium?.reasoningEffort ?? "medium",
 			high: variants.high?.reasoningEffort ?? "high",
 			xhigh: variants.xhigh?.reasoningEffort ?? "xhigh",
-			max: null,
+			max: variants.max?.reasoningEffort ?? fallback?.thinkingLevelMap?.max ?? null,
 		};
 		return [
 			{
@@ -470,8 +534,10 @@ function providerModelsFromStore(
 	return (entry?.models ?? []).flatMap((model: Model<Api>) => {
 		if (model.provider !== META_PROVIDER_ID || model.api !== "openai-responses")
 			return [];
+		// Re-gate on restore: a catalog cached while the fingerprint was enabled
+		// must not keep offering Contributor `max` after the user opts out.
 		return [
-			{
+			gateMuseMaxEffort({
 				id: model.id,
 				name: model.name,
 				api: model.api,
@@ -484,7 +550,7 @@ function providerModelsFromStore(
 				maxTokens: model.maxTokens,
 				headers: model.headers,
 				compat: model.compat as MetaProviderModel["compat"],
-			},
+			}),
 		];
 	});
 }
@@ -534,7 +600,7 @@ export async function refreshMetaModels(
 	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];
+		return cached.length > 0 ? cached : fallbackModels();
 	}
 	const apiKey =
 		context.credential?.type === "oauth"
@@ -544,7 +610,7 @@ export async function refreshMetaModels(
 				: undefined;
 	if (!apiKey) {
 		const cached = await cachedMetaModels(compatibleContext);
-		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+		return cached.length > 0 ? cached : fallbackModels();
 	}
 
 	try {
@@ -566,7 +632,7 @@ export async function refreshMetaModels(
 		const models = toProviderModels(body);
 		if (models.length === 0) {
 			const cached = await cachedMetaModels(compatibleContext);
-			return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+			return cached.length > 0 ? cached : fallbackModels();
 		}
 		if (!context.signal?.aborted) {
 			try {
@@ -582,7 +648,7 @@ export async function refreshMetaModels(
 	} catch (error) {
 		if (context.signal?.aborted) throw error;
 		const cached = await cachedMetaModels(compatibleContext);
-		return cached.length > 0 ? cached : [...FALLBACK_MODELS];
+		return cached.length > 0 ? cached : fallbackModels();
 	}
 }
 
@@ -601,6 +667,53 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 		: undefined;
 }
 
+/**
+ * Strict direct-endpoint check: https scheme, api.meta.ai hostname
+ * (case-insensitive), default port, and a bare /v1 path. WHATWG URL parsing
+ * normalizes the equivalent forms (uppercase host, explicit :443) to match;
+ * proxies, lookalike hosts (api.meta.ai.evil.com), subpaths, and
+ * non-default ports never match, so they never receive the fingerprint.
+ */
+export function isDirectMetaModelApiUrl(baseUrl: unknown): boolean {
+	if (typeof baseUrl !== "string" || !baseUrl) return false;
+	let parsed: URL;
+	try {
+		parsed = new URL(baseUrl);
+	} catch {
+		return false;
+	}
+	if (parsed.protocol !== "https:") return false;
+	if (parsed.hostname.toLowerCase() !== "api.meta.ai") return false;
+	if (parsed.port !== "") return false;
+	return parsed.pathname.replace(/\/+$/, "") === "/v1";
+}
+
+function hasUserAgentHeader(
+	headers: Record<string, string | null>,
+): boolean {
+	return Object.keys(headers).some(
+		(name) => name.toLowerCase() === "user-agent",
+	);
+}
+
+/**
+ * Setdefault the Muse fingerprint for direct Meta Model API requests.
+ * Explicit User-Agent headers (any casing, including null suppression)
+ * always win; anything but the direct endpoint is left untouched.
+ * Applies regardless of credential type: API-key and Muse Code login
+ * (minted) credentials both reach the same direct wire. Returns true when
+ * the fingerprint was applied.
+ */
+export function applyMetaUserAgentFingerprint(
+	headers: Record<string, string | null>,
+	baseUrl: unknown,
+): boolean {
+	if (!isDirectMetaModelApiUrl(baseUrl)) return false;
+	if (hasUserAgentHeader(headers)) return false;
+	headers["User-Agent"] = MUSE_USER_AGENT;
+	return true;
+}
+
 /**
  * Hermes-equivalent Responses hints for api.meta.ai:
  * setdefault `prompt_cache_retention: 24h`, and drop `reasoning.effort: none`
@@ -632,7 +745,7 @@ export function createMetaProviderConfig(): ProviderConfig {
 		baseUrl: META_API_BASE_URL,
 		api: "openai-responses",
 		apiKey: "$META_API_KEY",
-		models: [...FALLBACK_MODELS],
+		models: fallbackModels(),
 		refreshModels: refreshMetaModels,
 		oauth: {
 			name: "Meta Model API (browser login)",
@@ -662,4 +775,15 @@ export default function metaOAuthProvider(pi: ExtensionAPI): void {
 		if (ctx.model?.provider !== META_PROVIDER_ID) return undefined;
 		return applyMetaResponsesCacheHints(event.payload);
 	});
+	pi.on("before_provider_headers", (event, ctx) => {
+		const model = ctx.model;
+		if (model?.provider !== META_PROVIDER_ID) return;
+		// Opt-in only, and only for models that need it: every other Meta
+		// request keeps Pi's own User-Agent.
+		if (!MUSE_USER_AGENT_MODEL_IDS.has(model.id)) return;
+		if (!isMuseUserAgentEnabled()) return;
+		// The composed model always carries the effective baseUrl; without
+		// it the endpoint cannot be verified, so no fingerprint is sent.
+		applyMetaUserAgentFingerprint(event.headers, model.baseUrl);
+	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-meta-oauth",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Meta Model API OAuth provider for pi",
   "keywords": [
     "pi-package",
@@ -31,12 +31,12 @@
     "image": "https://raw.githubusercontent.com/BlockedPath/pi-meta-oauth/main/preview.png"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.83.0 <0.85.0",
-    "@earendil-works/pi-coding-agent": ">=0.83.0 <0.85.0"
+    "@earendil-works/pi-ai": ">=0.83.0 <0.88.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <0.88.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
     "bun-types": "latest",
     "typescript": "^5.9.0"
   },