@oh-my-pi/pi-ai 18.1.11 → 18.1.12

package/CHANGELOG.md

@@ -2,10 +2,17 @@
 
 ## [Unreleased]
 
+## [18.1.12] - 2026-09-06
+
+### Added
+
+- Added Muse Code subscription sign-in, credential refresh, inference, and quota reporting in `/usage`, with durable rate-limit backoff so quota refresh recovers instead of repeatedly retrying.
+
 ## [18.1.11] - 2026-09-05
 
 ### Fixed
 
+- Fixed OpenCode Go usage polls (`GET /zen/go/v1/usage`) missing `x-opencode-session` and omp's `User-Agent`: background polls now attribute with the stable install id so the requests OpenCode flags as `Bun fetch` carry the required session header.
 - GitHub Copilot sign-in now requests only basic profile access, restoring login for Enterprise organizations that reject repository, gist, and Codespaces permissions ([#10656](https://github.com/can1357/oh-my-pi/issues/10656)).
 
 ## [18.1.9] - 2026-09-04

package/dist/types/error/oauth.d.ts

@@ -22,6 +22,8 @@ export type OAuthErrorKind =
  | "configuration"
 /** Cloud project provisioning / onboarding (loadCodeAssist, onboardUser). */
  | "provisioning"
+/** Subscription/payment gate: plan required or purchase action needed. */
+ | "entitlement"
 /** OIDC / endpoint discovery failed. */
  | "discovery";
 export interface OAuthErrorOptions {

package/dist/types/index.d.ts

@@ -35,6 +35,7 @@ export * from "./usage/github-copilot.js";
 export * from "./usage/google-antigravity.js";
 export * from "./usage/kimi.js";
 export * from "./usage/minimax-code.js";
+export * from "./usage/muse-code.js";
 export * from "./usage/ollama.js";
 export * from "./usage/openai-codex.js";
 export * from "./usage/openai-codex-reset.js";

package/dist/types/providers/openai-shared.d.ts

@@ -357,11 +357,12 @@ export declare function resolveOpenAICompletionsOutputClamp(model: Model<"openai
 /**
  * Provider-specific Responses API output clamp.
  *
- * Meta documents a 131,072-token output limit for Muse Spark 1.1, so native
- * Meta requests may use the model's full advertised cap instead of the
- * conservative 64k OpenAI-compatible default.
+ * Models whose compiled provider policy opts in may use their full advertised
+ * output cap instead of the conservative 64k OpenAI-compatible default.
  */
-export declare function resolveOpenAIResponsesOutputClamp(model: Pick<Model, "provider" | "maxTokens">): number | undefined;
+export declare function resolveOpenAIResponsesOutputClamp(model: Pick<Model, "maxTokens"> & {
+    compat: Pick<ResolvedOpenAISharedCompat, "clampOutputToModelMax">;
+}): number | undefined;
 /**
  * Enable `tool_stream` for Z.AI/GLM-5.2 reasoning models when tools are present
  * (GLM-5.2 streams tool-call arguments incrementally and needs the flag to do so).
@@ -659,7 +660,7 @@ type CommonSamplingOptions = Pick<StreamOptions, "temperature" | "topP" | "topK"
  * reflect the model's context window rather than the upstream output limit.
  */
 export declare function applyCommonResponsesSamplingParams<P extends CommonResponsesParams>(params: P, options: CommonSamplingOptions | undefined, model: Pick<Model, "provider" | "api" | "id" | "omitMaxOutputTokens" | "maxTokens" | "identity"> & {
-    compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams" | "supportsPenaltyAndStopParams">;
+    compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams" | "supportsPenaltyAndStopParams" | "clampOutputToModelMax">;
 }): void;
 type ReasoningOptions = {
     reasoning?: string;

package/dist/types/registry/muse-code.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderTransport } from "./build.js";
+/** Muse stores both the Meta account token and its subscription-minted Model API key in one OAuth bearer. */
+export declare const museCodeTransport: ProviderTransport;

package/dist/types/registry/oauth/index.d.ts

@@ -22,6 +22,7 @@ export declare function unregisterOAuthProviders(sourceId: string): void;
  * Refresh a built-in OAuth grant, cancelling provider work when refresh ownership ends.
  */
 export declare function refreshOAuthToken(provider: OAuthProvider, credentials: OAuthCredentials, signal?: AbortSignal): Promise<OAuthCredentials>;
+export declare function normalizeOAuthCredentialExpiry<T extends OAuthCredentials>(provider: string, credentials: T): T;
 /**
  * Build API-key bytes for a provider from an already-fresh OAuth credential.
  *

package/dist/types/registry/oauth/muse-code.d.ts

@@ -0,0 +1,67 @@
+import type { AfterExchangeHook } from "../hooks/types.js";
+import type { FetchImpl } from "../../types.js";
+declare const museCodeKeyResponseSchema: import("@oh-my-pi/omptype").FluentType<{
+    action_url?: string | null | undefined;
+    api_key?: string | undefined;
+    is_subs_active?: boolean | undefined;
+    require_payment?: boolean | undefined;
+    require_payment_action_url?: string | undefined;
+    subs_tier_id?: string | undefined;
+    subs_tier_name?: string | undefined;
+    subs_usage?: {
+        weekly?: {
+            resets_at?: string | number | undefined;
+            used_percent?: number | undefined;
+            window_duration_mins?: number | undefined;
+        } | null | undefined;
+        window?: {
+            resets_at?: string | number | undefined;
+            used_percent?: number | undefined;
+            window_duration_mins?: number | undefined;
+        } | null | undefined;
+    } | null | undefined;
+    user_email?: string | undefined;
+    user_id?: string | undefined;
+}, {
+    action_url?: string | null | undefined;
+    api_key?: string | undefined;
+    is_subs_active?: boolean | undefined;
+    require_payment?: boolean | undefined;
+    require_payment_action_url?: string | undefined;
+    subs_tier_id?: string | undefined;
+    subs_tier_name?: string | undefined;
+    subs_usage?: {
+        weekly?: {
+            resets_at?: string | number | undefined;
+            used_percent?: number | undefined;
+            window_duration_mins?: number | undefined;
+        } | null | undefined;
+        window?: {
+            resets_at?: string | number | undefined;
+            used_percent?: number | undefined;
+            window_duration_mins?: number | undefined;
+        } | null | undefined;
+    } | null | undefined;
+    user_email?: string | undefined;
+    user_id?: string | undefined;
+}>;
+export type MuseCodeKeyResponse = typeof museCodeKeyResponseSchema.infer;
+declare const museCodeCredentialSchema: import("@oh-my-pi/omptype").FluentType<{
+    apiKey: string;
+    oauthAccessToken: string;
+}, {
+    apiKey: string;
+    oauthAccessToken: string;
+}>;
+export type MuseCodeCredential = typeof museCodeCredentialSchema.infer;
+export interface MuseCodeKeyRequestOptions {
+    fetch?: FetchImpl;
+    signal?: AbortSignal;
+    /** Ask Meta to onboard the account during an interactive login exchange. */
+    onboard?: boolean;
+}
+export declare function parseMuseCodeCredential(value: string): MuseCodeCredential;
+export declare function requestMuseCodeKey(accessToken: string, options?: MuseCodeKeyRequestOptions): Promise<MuseCodeKeyResponse>;
+/** Exchange Meta account access for the Model API key authorized by a Muse subscription. */
+export declare const attachMuseCodeApiKey: AfterExchangeHook;
+export {};

package/dist/types/usage/muse-code.d.ts

@@ -0,0 +1,2 @@
+import type { UsageProvider } from "../usage.js";
+export declare const museCodeUsageProvider: UsageProvider;

package/dist/types/usage.d.ts

@@ -478,6 +478,8 @@ export interface UsageProvider {
     validatesCredentials?: boolean;
     /** Whether a failed refresh may serve the previous successful report. Defaults to true. */
     retainLastGoodOnFailure?: boolean;
+    /** Provider-specific cool-down after a failed refresh. Defaults to the shared short backoff. */
+    failureBackoffMs?: number;
 }
 /** Request context used when ranking usage for a specific model. */
 export interface CredentialRankingContext {

package/dist/types/utils/schema/json-schema-validator.d.ts

@@ -16,5 +16,7 @@ export interface JsonSchemaValidationResult {
     success: boolean;
     issues: JsonSchemaValidationIssue[];
 }
+/** Whether any same-instance schema declaration or constraint owns this property name. */
+export declare function schemaDefinesProperty(schema: unknown, key: string): boolean;
 export declare function validateJsonSchemaValue(schema: unknown, value: unknown): JsonSchemaValidationResult;
 export declare function isJsonSchemaValueValid(schema: unknown, value: unknown): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.1.11",
+	"version": "18.1.12",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -124,11 +124,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.1.11",
-		"@oh-my-pi/pi-catalog": "18.1.11",
-		"@oh-my-pi/pi-natives": "18.1.11",
-		"@oh-my-pi/pi-utils": "18.1.11",
-		"@oh-my-pi/pi-wire": "18.1.11"
+		"@oh-my-pi/omptype": "18.1.12",
+		"@oh-my-pi/pi-catalog": "18.1.12",
+		"@oh-my-pi/pi-natives": "18.1.12",
+		"@oh-my-pi/pi-utils": "18.1.12",
+		"@oh-my-pi/pi-wire": "18.1.12"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth-storage.ts

@@ -21,7 +21,7 @@ import type { ApiKeyResolver } from "./auth-retry";
 import * as AIError from "./error";
 import { isUsageLimitOutcome } from "./error/rate-limit";
 import { getProviderDefinition, PASTE_CODE_LOGIN_PROVIDERS } from "./registry";
-import { getOAuthApiKey, getOAuthProvider, refreshOAuthToken } from "./registry/oauth";
+import { getOAuthApiKey, getOAuthProvider, normalizeOAuthCredentialExpiry, refreshOAuthToken } from "./registry/oauth";
 import type {
 	OAuthAuthInfo,
 	OAuthController,
@@ -59,6 +59,7 @@ import { googleGeminiCliUsageProvider } from "./usage/gemini";
 import { githubCopilotUsageProvider } from "./usage/github-copilot";
 import { antigravityRankingStrategy, antigravityUsageProvider } from "./usage/google-antigravity";
 import { kimiRankingStrategy, kimiUsageProvider } from "./usage/kimi";
+import { museCodeUsageProvider } from "./usage/muse-code";
 import { minimaxCodeUsageProvider } from "./usage/minimax-code";
 import { ollamaCloudUsageProvider, ollamaUsageProvider } from "./usage/ollama";
 import { codexRankingStrategy, openaiCodexUsageProvider } from "./usage/openai-codex";
@@ -661,6 +662,7 @@ const DEFAULT_USAGE_PROVIDERS: UsageProvider[] = [
 	openaiCodexUsageProvider,
 	kimiUsageProvider,
 	minimaxCodeUsageProvider,
+	museCodeUsageProvider,
 	antigravityUsageProvider,
 	googleGeminiCliUsageProvider,
 	ollamaUsageProvider,
@@ -3601,13 +3603,14 @@ export class AuthStorage {
 			// re-hit the endpoint on every poll. Most providers serve the last good
 			// value through transient failures. Session-cookie providers can opt out
 			// so an expired login does not display stale quota indefinitely.
-			const retainLastGood =
-				!forceRefresh && this.#resolveUsageProvider(request.provider)?.retainLastGoodOnFailure !== false;
+			const providerImpl = this.#resolveUsageProvider(request.provider);
+			const retainLastGood = !forceRefresh && providerImpl?.retainLastGoodOnFailure !== false;
 			const lastGood = retainLastGood
 				? (this.#usageCache.getStale<UsageReport | null>(cacheKey)?.value ?? null)
 				: null;
-			const backoffJitter = USAGE_FAILURE_BACKOFF_MS * (Math.random() * 0.5 - 0.25);
-			const coolDown = Date.now() + USAGE_FAILURE_BACKOFF_MS + backoffJitter;
+			const failureBackoffMs = providerImpl?.failureBackoffMs ?? USAGE_FAILURE_BACKOFF_MS;
+			const backoffJitter = failureBackoffMs * (Math.random() * 0.5 - 0.25);
+			const coolDown = Date.now() + failureBackoffMs + backoffJitter;
 			this.#usageCache.set(cacheKey, { value: lastGood, expiresAt: coolDown });
 			return lastGood;
 		})().finally(() => {
@@ -5484,6 +5487,7 @@ export class AuthStorage {
 		credentialId: number | undefined,
 		signal?: AbortSignal,
 	): Promise<OAuthCredentials> {
+		credential = normalizeOAuthCredentialExpiry(provider, credential);
 		if (credentialId !== undefined) {
 			const existing = this.#oauthCredentialRefreshInFlight.get(credentialId);
 			if (existing) return raceCredentialRefreshWithSignal(existing, signal);

package/src/error/oauth.ts

@@ -24,6 +24,8 @@ export type OAuthErrorKind =
 	| "configuration"
 	/** Cloud project provisioning / onboarding (loadCodeAssist, onboardUser). */
 	| "provisioning"
+	/** Subscription/payment gate: plan required or purchase action needed. */
+	| "entitlement"
 	/** OIDC / endpoint discovery failed. */
 	| "discovery";
 

package/src/index.ts

@@ -35,6 +35,7 @@ export * from "./usage/github-copilot";
 export * from "./usage/google-antigravity";
 export * from "./usage/kimi";
 export * from "./usage/minimax-code";
+export * from "./usage/muse-code";
 export * from "./usage/ollama";
 export * from "./usage/openai-codex";
 export * from "./usage/openai-codex-reset";

package/src/providers/openai-shared.ts

@@ -1238,12 +1238,13 @@ export function resolveOpenAICompletionsOutputClamp(
 /**
  * Provider-specific Responses API output clamp.
  *
- * Meta documents a 131,072-token output limit for Muse Spark 1.1, so native
- * Meta requests may use the model's full advertised cap instead of the
- * conservative 64k OpenAI-compatible default.
+ * Models whose compiled provider policy opts in may use their full advertised
+ * output cap instead of the conservative 64k OpenAI-compatible default.
  */
-export function resolveOpenAIResponsesOutputClamp(model: Pick<Model, "provider" | "maxTokens">): number | undefined {
-	if (model.provider === "meta") {
+export function resolveOpenAIResponsesOutputClamp(
+	model: Pick<Model, "maxTokens"> & { compat: Pick<ResolvedOpenAISharedCompat, "clampOutputToModelMax"> },
+): number | undefined {
+	if (model.compat.clampOutputToModelMax) {
 		return model.maxTokens ?? OPENAI_MAX_OUTPUT_TOKENS;
 	}
 	return undefined;
@@ -3573,7 +3574,10 @@ export function applyCommonResponsesSamplingParams<P extends CommonResponsesPara
 	params: P,
 	options: CommonSamplingOptions | undefined,
 	model: Pick<Model, "provider" | "api" | "id" | "omitMaxOutputTokens" | "maxTokens" | "identity"> & {
-		compat: Pick<ResolvedOpenAISharedCompat, "supportsSamplingParams" | "supportsPenaltyAndStopParams">;
+		compat: Pick<
+			ResolvedOpenAISharedCompat,
+			"supportsSamplingParams" | "supportsPenaltyAndStopParams" | "clampOutputToModelMax"
+		>;
 	},
 ): void {
 	if (options?.maxTokens && !model.omitMaxOutputTokens) {

package/src/registry/engine/common.ts

@@ -158,16 +158,20 @@ export function mapCredentials(
 			break;
 		case "seconds": {
 			const seconds = jsonPath(body, expiry.path);
-			if (typeof seconds !== "number" || !Number.isFinite(seconds)) {
-				throw new AIError.OAuthError(`${provider} token response missing ${expiry.path}`, {
-					kind: "validation",
-					provider,
-				});
+			if (typeof seconds === "number" && Number.isFinite(seconds)) {
+				const from = expiry.fromPath ? jsonPath(body, expiry.fromPath) : undefined;
+				const base = typeof from === "number" && Number.isFinite(from) ? from * 1000 : Date.now();
+				expires = base + seconds * 1000 - expiry.skewMs;
+				break;
 			}
-			const from = expiry.fromPath ? jsonPath(body, expiry.fromPath) : undefined;
-			const base = typeof from === "number" && Number.isFinite(from) ? from * 1000 : Date.now();
-			expires = base + seconds * 1000 - expiry.skewMs;
-			break;
+			if (expiry.fallbackMs !== undefined) {
+				expires = Date.now() + expiry.fallbackMs;
+				break;
+			}
+			throw new AIError.OAuthError(`${provider} token response missing ${expiry.path}`, {
+				kind: "validation",
+				provider,
+			});
 		}
 	}
 	const credentials: OAuthCredentials = {

package/src/registry/hooks/device-code.ts

@@ -10,4 +10,6 @@ export const DEVICE_CODE_HEADERS_HOOKS: Record<string, Lazy<HeadersHook>> = {
 export const DEVICE_CODE_VALUE_HOOKS: Record<string, Lazy<ValueHook>> = {
 	"xai-token-endpoint": () => import("../oauth/xai-oauth").then(module => module.getXAITokenEndpoint),
 };
-export const DEVICE_CODE_AFTER_EXCHANGE_HOOKS: Record<string, Lazy<AfterExchangeHook>> = {};
+export const DEVICE_CODE_AFTER_EXCHANGE_HOOKS: Record<string, Lazy<AfterExchangeHook>> = {
+	"muse-code-key": () => import("../oauth/muse-code").then(module => module.attachMuseCodeApiKey),
+};

package/src/registry/muse-code.ts

@@ -0,0 +1,23 @@
+import { parseMuseCodeCredential } from "./oauth/muse-code";
+import type { ProviderTransport } from "./build";
+
+/** Muse stores both the Meta account token and its subscription-minted Model API key in one OAuth bearer. */
+export const museCodeTransport: ProviderTransport = {
+	prepareRequest: (model, options) => {
+		if (!options.apiKey) return { model, options };
+		const { apiKey } = parseMuseCodeCredential(options.apiKey);
+		return {
+			model,
+			options: {
+				...options,
+				apiKey,
+				headers: { "x-api-version": "1.0.0", ...options.headers },
+			},
+		};
+	},
+	prepareModelDiscovery: config => {
+		if (!config.apiKey) return { ...config, authenticated: false };
+		const { apiKey } = parseMuseCodeCredential(config.apiKey);
+		return { ...config, apiKey, authenticated: true };
+	},
+};

package/src/registry/oauth/index.ts

@@ -87,7 +87,19 @@ export async function refreshOAuthToken(
 	return def.refreshToken ? def.refreshToken(credentials, signal) : credentials;
 }
 const JWT_EXPIRY_SKEW_MS = 5 * 60_000;
+export function normalizeOAuthCredentialExpiry<T extends OAuthCredentials>(provider: string, credentials: T): T {
+	if (authPolicyFor(provider)?.expiry !== "jwt-or-never") return credentials;
 
+	// Trust a JWT expiry claim when present; otherwise treat providers with
+	// non-expiring sessions as such rather than honoring stale stored expiry
+	// timestamps written by older login implementations.
+	const normalizedExpires =
+		credentials.expires > 0 && credentials.expires < 10_000_000_000
+			? credentials.expires * 1000
+			: credentials.expires;
+	const expires = jwtExpiryMs(credentials.access, JWT_EXPIRY_SKEW_MS) ?? Math.max(normalizedExpires, NEVER_EXPIRES);
+	return expires === credentials.expires ? credentials : ({ ...credentials, expires } as T);
+}
 /**
  * Build API-key bytes for a provider from an already-fresh OAuth credential.
  *
@@ -110,20 +122,7 @@ export async function getOAuthApiKey(
 	}
 
 	const policy = authPolicyFor(provider);
-	const jwtOrNever = policy?.expiry === "jwt-or-never";
-	if (jwtOrNever) {
-		// Session JWTs (Perplexity) usually omit `exp` (server-side sessions).
-		// Trust the JWT claim when present; otherwise treat the credential as
-		// non-expiring rather than honoring a stale stored `expires` (older
-		// logins wrote loginTime+1h).
-		const normalizedExpires =
-			creds.expires > 0 && creds.expires < 10_000_000_000 ? creds.expires * 1000 : creds.expires;
-		const jwtExpiry = jwtExpiryMs(creds.access, JWT_EXPIRY_SKEW_MS);
-		const expires = jwtExpiry ?? Math.max(normalizedExpires, NEVER_EXPIRES);
-		if (expires !== creds.expires) {
-			creds = { ...creds, expires };
-		}
-	}
+	creds = normalizeOAuthCredentialExpiry(provider, creds);
 	// Refresh is the sole responsibility of `AuthStorage` (which calls
 	// `refreshOAuthToken` directly with broker-aware single-flighting). If we
 	// reach here with an expired credential, the outer pipeline failed to
@@ -132,13 +131,6 @@ export async function getOAuthApiKey(
 	// trigger a `__remote__`-against-real-provider failure that gets classified
 	// as `invalid_grant` and disables the row. Refuse loudly instead.
 	if (Date.now() >= creds.expires) {
-		if (jwtOrNever) {
-			const jwtExpiry = jwtExpiryMs(creds.access, JWT_EXPIRY_SKEW_MS);
-			if (jwtExpiry && Date.now() < jwtExpiry) {
-				const fallbackCredentials = { ...creds, expires: jwtExpiry };
-				return { newCredentials: fallbackCredentials, apiKey: fallbackCredentials.access };
-			}
-		}
 		throw new AIError.OAuthError(
 			`OAuth credential for ${provider} is expired and must be refreshed via AuthStorage before getOAuthApiKey is called`,
 			{ kind: "validation", provider },

package/src/registry/oauth/muse-code.ts

@@ -0,0 +1,174 @@
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../../error";
+import type { AfterExchangeHook, ExchangeContext } from "../hooks/types";
+import type { FetchImpl } from "../../types";
+import type { OAuthCredentials } from "./types";
+
+const PROVIDER = "muse-code";
+const MUSE_KEY_URL = "https://api.meta.ai/muse-code/key";
+const API_VERSION = "1.0.0";
+const REQUEST_TIMEOUT_MS = 20_000;
+
+const subscriptionWindowSchema = type({
+	"used_percent?": "number",
+	"resets_at?": "string | number",
+	"window_duration_mins?": "number",
+});
+
+const subscriptionUsageSchema = type({
+	"window?": subscriptionWindowSchema.or("null"),
+	"weekly?": subscriptionWindowSchema.or("null"),
+});
+
+const museCodeKeyResponseSchema = type({
+	"api_key?": "string",
+	"require_payment_action_url?": "string",
+	"require_payment?": "boolean",
+	"action_url?": "string | null",
+	"user_email?": "string",
+	"user_id?": "string",
+	"is_subs_active?": "boolean",
+	"subs_tier_id?": "string",
+	"subs_tier_name?": "string",
+	"subs_usage?": subscriptionUsageSchema.or("null"),
+});
+export type MuseCodeKeyResponse = typeof museCodeKeyResponseSchema.infer;
+
+const museCodeCredentialSchema = type({
+	oauthAccessToken: "string",
+	apiKey: "string",
+});
+export type MuseCodeCredential = typeof museCodeCredentialSchema.infer;
+export interface MuseCodeKeyRequestOptions {
+	fetch?: FetchImpl;
+	signal?: AbortSignal;
+	/** Ask Meta to onboard the account during an interactive login exchange. */
+	onboard?: boolean;
+}
+
+function requestSignal(signal?: AbortSignal): AbortSignal {
+	const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+export function parseMuseCodeCredential(value: string): MuseCodeCredential {
+	let payload: unknown;
+	try {
+		payload = JSON.parse(value);
+	} catch (cause) {
+		throw new AIError.ConfigurationError("Muse Code credential is invalid; sign in again", { cause });
+	}
+	const parsed = museCodeCredentialSchema(payload);
+	if (parsed instanceof type.errors || !parsed.oauthAccessToken.trim() || !parsed.apiKey.trim()) {
+		throw new AIError.ConfigurationError("Muse Code credential is invalid; sign in again");
+	}
+	return parsed;
+}
+
+function encodeMuseCodeCredential(oauthAccessToken: string, apiKey: string): string {
+	return JSON.stringify({ oauthAccessToken, apiKey });
+}
+
+export async function requestMuseCodeKey(
+	accessToken: string,
+	options: MuseCodeKeyRequestOptions = {},
+): Promise<MuseCodeKeyResponse> {
+	const response = await (options.fetch ?? fetch)(MUSE_KEY_URL, {
+		method: "POST",
+		headers: {
+			Accept: "application/json",
+			Authorization: `Bearer ${accessToken}`,
+			"Content-Type": "application/json",
+			"x-api-version": API_VERSION,
+		},
+		body: JSON.stringify(options.onboard ? { onboard: true } : {}),
+		redirect: "error",
+		signal: requestSignal(options.signal),
+	});
+	const text = await response.text();
+	if (!response.ok) {
+		const excerpt = text.trim() ? ` ${text.slice(0, 500).trim()}` : "";
+		throw new AIError.OAuthError(`Muse Code key exchange failed: ${response.status}${excerpt}`, {
+			kind: "token-exchange",
+			provider: PROVIDER,
+			status: response.status,
+		});
+	}
+	let payload: unknown;
+	try {
+		payload = JSON.parse(text);
+	} catch (cause) {
+		throw new AIError.OAuthError("Muse Code key exchange returned invalid JSON", {
+			kind: "validation",
+			provider: PROVIDER,
+			status: response.status,
+			cause,
+		});
+	}
+	const parsed = museCodeKeyResponseSchema(payload);
+	if (parsed instanceof type.errors) {
+		throw new AIError.OAuthError(`Invalid Muse Code key response: ${parsed.summary}`, {
+			kind: "validation",
+			provider: PROVIDER,
+		});
+	}
+	return parsed;
+}
+
+/** Exchange Meta account access for the Model API key authorized by a Muse subscription. */
+export const attachMuseCodeApiKey: AfterExchangeHook = async (
+	credentials: OAuthCredentials,
+	context: ExchangeContext,
+): Promise<OAuthCredentials> => {
+	// Reuse an already-minted subscription key instead of re-minting on every
+	// token refresh. The key endpoint is aggressively rate-limited (429s), and
+	// Meta returns the same api_key for the account, so a refresh that already
+	// carries one must not burn another key call. Only a login/refresh without
+	// one (first login, or a previously failed mint) re-mints here.
+	try {
+		const existing = parseMuseCodeCredential(credentials.access);
+		if (existing.apiKey.trim()) return credentials;
+	} catch {
+		// No usable minted key yet — fall through to mint one.
+	}
+	const payload = await requestMuseCodeKey(credentials.access, {
+		fetch: context.fetch,
+		signal: context.signal,
+		onboard: true,
+	});
+	if (payload.is_subs_active === false) {
+		throw new AIError.OAuthError("invalid_grant: Muse Code subscription is inactive", {
+			kind: "token-exchange",
+			provider: PROVIDER,
+			status: 403,
+		});
+	}
+	const apiKey = payload.api_key?.trim() || "";
+	if (!apiKey) {
+		const actionUrl = payload.action_url?.trim() || payload.require_payment_action_url?.trim();
+		if (payload.require_payment === true || actionUrl) {
+			throw new AIError.OAuthError(
+				actionUrl ? `Muse Code subscription is required: ${actionUrl}` : "Muse Code subscription is required",
+				{ kind: "entitlement", provider: PROVIDER },
+			);
+		}
+		throw new AIError.OAuthError("Muse Code key response is missing api_key", {
+			kind: "validation",
+			provider: PROVIDER,
+		});
+	}
+	const email = payload.user_email?.trim().toLowerCase();
+	const accountId = payload.user_id?.trim() || email;
+	if (!accountId) {
+		throw new AIError.OAuthError("Muse Code key response is missing a stable account identity", {
+			kind: "validation",
+			provider: PROVIDER,
+		});
+	}
+	return {
+		...credentials,
+		access: encodeMuseCodeCredential(credentials.access, apiKey),
+		accountId,
+		email,
+	};
+};

package/src/registry/registry.ts

@@ -5,6 +5,7 @@ import { amazonBedrockTransport } from "./amazon-bedrock";
 import { bedrockMantleTransport } from "./bedrock-mantle";
 import { buildProviderDefinition, type ProviderTransport } from "./build";
 import { cloudflareAiGatewayTransport } from "./cloudflare-ai-gateway";
+import { museCodeTransport } from "./muse-code";
 import type { ProviderDefinition } from "./types";
 
 /**
@@ -16,6 +17,7 @@ const TRANSPORTS: Record<string, ProviderTransport> = {
 	"amazon-bedrock": amazonBedrockTransport,
 	"bedrock-mantle": bedrockMantleTransport,
 	"cloudflare-ai-gateway": cloudflareAiGatewayTransport,
+	"muse-code": museCodeTransport,
 };
 
 /**

package/src/usage/muse-code.ts

@@ -0,0 +1,158 @@
+import * as AIError from "../error";
+import { parseMuseCodeCredential, requestMuseCodeKey, type MuseCodeKeyResponse } from "../registry/oauth/muse-code";
+import type { UsageAmount, UsageFetchParams, UsageLimit, UsageProvider, UsageReport, UsageWindow } from "../usage";
+import { parseIsoTimestamp, parsePositiveTimestamp, usageStatus, WEEK_MS } from "./shared";
+
+const PROVIDER = "muse-code";
+const SOURCE = "api.meta.ai/muse-code/key";
+const FAILURE_BACKOFF_MS = 5 * 60_000;
+
+function parseResetTimestamp(value: string | number | undefined): number | undefined {
+	return typeof value === "string" ? parseIsoTimestamp(value) : parsePositiveTimestamp(value);
+}
+
+function percentAmount(usedPercent: number): UsageAmount {
+	const used = Math.min(usedPercent, 100);
+	const usedFraction = used / 100;
+	return {
+		used,
+		limit: 100,
+		remaining: 100 - used,
+		usedFraction,
+		remainingFraction: 1 - usedFraction,
+		unit: "percent",
+	};
+}
+
+function buildLimit(
+	id: string,
+	label: string,
+	usedPercent: number | undefined,
+	window: UsageWindow,
+	tier: string | undefined,
+	accountId: string | undefined,
+): UsageLimit | undefined {
+	if (typeof usedPercent !== "number" || !Number.isFinite(usedPercent) || usedPercent < 0) return undefined;
+	const amount = percentAmount(usedPercent);
+	return {
+		id,
+		label,
+		scope: { provider: PROVIDER, accountId, tier, windowId: window.id, shared: true },
+		window,
+		amount,
+		status: usageStatus(amount.usedFraction),
+	};
+}
+
+function formatRollingWindowLabel(minutes: number | undefined): string {
+	if (minutes === undefined) return "Rolling Window";
+	if (minutes % 60 === 0) {
+		const hours = minutes / 60;
+		return `${hours} ${hours === 1 ? "Hour" : "Hours"}`;
+	}
+	return `${minutes} ${minutes === 1 ? "Minute" : "Minutes"}`;
+}
+
+function buildLimits(payload: MuseCodeKeyResponse, accountId: string | undefined): UsageLimit[] {
+	const usage = payload.subs_usage;
+	if (!usage) return [];
+	const tier = payload.subs_tier_name?.trim() || payload.subs_tier_id?.trim() || undefined;
+	const limits: UsageLimit[] = [];
+	if (usage.window) {
+		const minutes = usage.window.window_duration_mins;
+		const durationMs =
+			typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0 ? minutes * 60_000 : undefined;
+		const label = formatRollingWindowLabel(
+			typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0 ? Math.round(minutes) : undefined,
+		);
+		const id = durationMs === undefined ? "rolling" : `${Math.round(durationMs / 60_000)}m`;
+		const limit = buildLimit(
+			id,
+			label,
+			usage.window.used_percent,
+			{
+				id,
+				label,
+				durationMs,
+				resetsAt: parseResetTimestamp(usage.window.resets_at),
+			},
+			tier,
+			accountId,
+		);
+		if (limit) limits.push(limit);
+	}
+	if (usage.weekly) {
+		const limit = buildLimit(
+			"1w",
+			"Weekly",
+			usage.weekly.used_percent,
+			{
+				id: "1w",
+				label: "Weekly",
+				durationMs: WEEK_MS,
+				resetsAt: parseResetTimestamp(usage.weekly.resets_at),
+			},
+			tier,
+			accountId,
+		);
+		if (limit) limits.push(limit);
+	}
+	return limits;
+}
+
+export const museCodeUsageProvider: UsageProvider = {
+	id: PROVIDER,
+	validatesCredentials: true,
+	failureBackoffMs: FAILURE_BACKOFF_MS,
+
+	supports(params: UsageFetchParams): boolean {
+		if (params.provider !== PROVIDER || params.credential.type !== "oauth" || !params.credential.accessToken) {
+			return false;
+		}
+		try {
+			parseMuseCodeCredential(params.credential.accessToken);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+
+	async fetchUsage(params, ctx): Promise<UsageReport | null> {
+		if (params.provider !== PROVIDER || params.credential.type !== "oauth") return null;
+		const encodedCredential = params.credential.accessToken?.trim();
+		if (!encodedCredential) return null;
+		const { oauthAccessToken } = parseMuseCodeCredential(encodedCredential);
+
+		let payload: MuseCodeKeyResponse;
+		try {
+			payload = await requestMuseCodeKey(oauthAccessToken, { fetch: ctx.fetch, signal: params.signal });
+		} catch (error) {
+			if (error instanceof AIError.OAuthError && (error.status === 401 || error.status === 403)) {
+				throw new AIError.ProviderHttpError(error.message, error.status, { cause: error });
+			}
+			return null;
+		}
+		if (payload.is_subs_active === false) {
+			throw new AIError.ProviderHttpError("Muse Code subscription is inactive", 403);
+		}
+		const email = payload.user_email?.trim().toLowerCase() || params.credential.email;
+		const accountId = payload.user_id?.trim() || params.credential.accountId || email;
+		const limits = buildLimits(payload, accountId);
+		if (limits.length === 0) return null;
+		const raw = { ...payload };
+		delete raw.api_key;
+
+		return {
+			provider: PROVIDER,
+			fetchedAt: Date.now(),
+			limits,
+			metadata: {
+				source: SOURCE,
+				...(email ? { email } : {}),
+				...(accountId ? { accountId } : {}),
+				...(payload.subs_tier_name ? { tier: payload.subs_tier_name } : {}),
+			},
+			raw,
+		};
+	},
+};

package/src/usage/opencode-go.ts

@@ -1,3 +1,4 @@
+import { USER_AGENT, getInstallId } from "@oh-my-pi/pi-utils";
 import { ProviderHttpError } from "../error";
 import type {
 	CredentialRankingStrategy,
@@ -108,6 +109,13 @@ async function fetchOpenCodeGoUsage(params: UsageFetchParams, ctx: UsageFetchCon
 			headers: {
 				accept: "application/json",
 				authorization: `Bearer ${credential.apiKey}`,
+				// Background poll outside any conversation: attribute with the
+				// stable install id so OpenCode can optimize/service the
+				// request (x-opencode-session required from 09/06). Peers
+				// (codex/zai) send USER_AGENT here; without it Bun's default
+				// UA is what upstream flags as "Bun fetch".
+				"User-Agent": USER_AGENT,
+				"x-opencode-session": getInstallId(),
 			},
 			signal: params.signal,
 		});

package/src/usage.ts

@@ -359,6 +359,8 @@ export interface UsageProvider {
 	validatesCredentials?: boolean;
 	/** Whether a failed refresh may serve the previous successful report. Defaults to true. */
 	retainLastGoodOnFailure?: boolean;
+	/** Provider-specific cool-down after a failed refresh. Defaults to the shared short backoff. */
+	failureBackoffMs?: number;
 }
 
 /** Request context used when ranking usage for a specific model. */

package/src/utils/schema/json-schema-validator.ts

@@ -173,6 +173,120 @@ function resolveLocalRef(root: unknown, ref: string): unknown | undefined {
 	return current;
 }
 
+/** A presence-only constraint, as distinct from restrictions on a property's value. */
+function requiresOnlyPropertyPresence(schema: unknown, key: string, root: unknown, depth = 0): boolean {
+	if (!isJsonObject(schema) || depth >= MAX_REF_DEPTH) return false;
+	for (const keyword of Object.keys(schema)) {
+		switch (keyword) {
+			case "required":
+			case "type":
+			case "$ref":
+			case "description":
+			case "title":
+			case "$comment":
+				break;
+			default:
+				return false;
+		}
+	}
+	if ("$ref" in schema) {
+		if (typeof schema.$ref !== "string" || schema.required !== undefined || schema.type !== undefined) return false;
+		return requiresOnlyPropertyPresence(resolveLocalRef(root, schema.$ref), key, root, depth + 1);
+	}
+	return (
+		(schema.type === undefined || schema.type === "object") &&
+		Array.isArray(schema.required) &&
+		schema.required.includes(key) &&
+		schema.required.every(entry => typeof entry === "string")
+	);
+}
+
+/** Whether any same-instance schema declaration or constraint owns this property name. */
+export function schemaDefinesProperty(schema: unknown, key: string): boolean {
+	const root = schema;
+	const visited = new WeakMap<object, number>();
+	const visit = (node: unknown, context: "positive" | "negative" | "predicate" = "positive"): boolean => {
+		if (!isJsonObject(node)) return false;
+		const contextBit = context === "positive" ? 1 : context === "negative" ? 2 : 4;
+		const previousContexts = visited.get(node) ?? 0;
+		if (previousContexts & contextBit) return false;
+		visited.set(node, previousContexts | contextBit);
+		if (isJsonObject(node.const) && Object.hasOwn(node.const, key)) return true;
+		if (Array.isArray(node.enum) && node.enum.some(value => isJsonObject(value) && Object.hasOwn(value, key))) {
+			return true;
+		}
+		const properties = node.properties;
+		if (isJsonObject(properties) && Object.hasOwn(properties, key)) {
+			return properties[key] !== false || context !== "positive";
+		}
+		const required = node.required;
+		if (Array.isArray(required) && required.includes(key)) return true;
+		if (
+			node.propertyNames !== undefined &&
+			node.additionalProperties !== false &&
+			validateSchemaValueInRoot(node.propertyNames, key, root).success
+		) {
+			return true;
+		}
+		const patternProperties = node.patternProperties;
+		if (isJsonObject(patternProperties)) {
+			for (const [pattern, patternSchema] of Object.entries(patternProperties)) {
+				try {
+					if (new RegExp(pattern).test(key)) {
+						if (patternSchema !== false) return true;
+					}
+				} catch {
+					// Invalid patterns are rejected by validation and cannot declare ownership.
+				}
+			}
+		}
+		if (isJsonObject(node.unevaluatedProperties)) return true;
+		if (isJsonObject(node.additionalProperties)) return true;
+		for (const keyword of ["anyOf", "oneOf", "allOf"] as const) {
+			const branches = node[keyword];
+			if (Array.isArray(branches) && branches.some(branch => visit(branch, context))) return true;
+		}
+		if (visit(node.if, "predicate")) return true;
+		for (const keyword of ["then", "else"] as const) {
+			if (visit(node[keyword], context)) return true;
+		}
+		// `not: { required: [key] }` forbids the name rather than declaring data.
+		// Negated value constraints still own their inputs and must be validated.
+		if (
+			(context !== "positive" || !requiresOnlyPropertyPresence(node.not, key, root)) &&
+			visit(node.not, context === "predicate" ? "predicate" : context === "positive" ? "negative" : "positive")
+		) {
+			return true;
+		}
+		const dependentSchemas = node.dependentSchemas;
+		if (isJsonObject(dependentSchemas)) {
+			if (Object.hasOwn(dependentSchemas, key)) return true;
+			if (Object.values(dependentSchemas).some(dependency => visit(dependency, context))) return true;
+		}
+		const dependentRequired = node.dependentRequired;
+		if (isJsonObject(dependentRequired)) {
+			if (Object.hasOwn(dependentRequired, key)) return true;
+			for (const dependencies of Object.values(dependentRequired)) {
+				if (Array.isArray(dependencies) && dependencies.includes(key)) return true;
+			}
+		}
+		const dependencies = node.dependencies;
+		if (isJsonObject(dependencies)) {
+			if (Object.hasOwn(dependencies, key)) return true;
+			for (const dependency of Object.values(dependencies)) {
+				if (Array.isArray(dependency) && dependency.includes(key)) return true;
+				if (visit(dependency, context)) return true;
+			}
+		}
+		if (typeof node.$ref === "string") {
+			const resolved = resolveLocalRef(root, node.$ref);
+			if (resolved !== undefined && visit(resolved, context)) return true;
+		}
+		return false;
+	};
+	return visit(schema);
+}
+
 /** Resolve a `#/path/to/node` pointer against the root schema. Returns `undefined` for external/unsupported refs. */
 
 function isRequiredSet(value: unknown): value is string[] {
@@ -615,18 +729,22 @@ function validateNumberKeywords(
 	return valid;
 }
 
-export function validateJsonSchemaValue(schema: unknown, value: unknown): JsonSchemaValidationResult {
+function validateSchemaValueInRoot(schema: unknown, value: unknown, root: unknown): JsonSchemaValidationResult {
 	const issues: JsonSchemaValidationIssue[] = [];
 	const success = validateSchemaNode(
 		schema,
 		value,
 		[],
-		{ root: schema, seenPairs: new Set(), objectIds: new WeakMap(), nextObjectId: { value: 0 }, refDepth: 0 },
+		{ root, seenPairs: new Set(), objectIds: new WeakMap(), nextObjectId: { value: 0 }, refDepth: 0 },
 		issues,
 	);
 	return { success, issues };
 }
 
+export function validateJsonSchemaValue(schema: unknown, value: unknown): JsonSchemaValidationResult {
+	return validateSchemaValueInRoot(schema, value, schema);
+}
+
 export function isJsonSchemaValueValid(schema: unknown, value: unknown): boolean {
 	return validateJsonSchemaValue(schema, value).success;
 }