@oh-my-pi/pi-ai 17.1.8 → 17.2.0

package/dist/types/registry/exa.d.ts

@@ -0,0 +1,8 @@
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
+export declare const loginExa: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
+export declare const exaProvider: {
+    readonly id: "exa";
+    readonly name: "Exa";
+    readonly envKeys: "EXA_API_KEY";
+    readonly login: (cb: OAuthLoginCallbacks) => Promise<string>;
+};

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

@@ -64,6 +64,11 @@ declare const ALL: ({
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<string>;
     readonly callbackPort: 59653;
     readonly pasteCodeFlow: true;
+} | {
+    readonly id: "exa";
+    readonly name: "Exa";
+    readonly envKeys: "EXA_API_KEY";
+    readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<string>;
 } | {
     readonly id: "firepass";
     readonly name: "Fire Pass (Fireworks Kimi K2.6 Turbo subscription)";
@@ -282,7 +287,8 @@ declare const ALL: ({
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<string>;
 } | {
     readonly id: "xai";
-    readonly name: "xAI";
+    readonly name: "xAI API";
+    readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<string>;
 } | {
     readonly id: "xai-oauth";
     readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";

package/dist/types/registry/xai.d.ts

@@ -1,4 +1,7 @@
+import type { OAuthLoginCallbacks } from "./oauth/types.js";
+export declare const loginXAI: (options: import("./oauth/index.js").OAuthController) => Promise<string>;
 export declare const xaiProvider: {
     readonly id: "xai";
-    readonly name: "xAI";
+    readonly name: "xAI API";
+    readonly login: (cb: OAuthLoginCallbacks) => Promise<string>;
 };

package/dist/types/stream.d.ts

@@ -5,6 +5,8 @@ import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli.js";
 import type { GoogleVertexOptions } from "./providers/google-vertex.js";
 import type { Api, AssistantMessage, Context, Model, OptionsForApi, SimpleStreamOptions, ToolChoice } from "./types.js";
 import { AssistantMessageEventStream } from "./utils/event-stream.js";
+/** Strict official-Codex endpoint check; exact origin or a path boundary after {@link CODEX_BASE_URL}. */
+export declare function isOfficialCodexApiUrl(baseUrl: string | undefined): boolean;
 export declare function configureProviderMaxInFlightRequests(limits: Record<string, number> | undefined): void;
 export declare const __providerInFlightForTesting: {
     setRoot(root: string | undefined): void;

package/dist/types/types.d.ts

@@ -1,6 +1,6 @@
 export * from "@oh-my-pi/pi-catalog/effort";
 export * from "@oh-my-pi/pi-catalog/types";
-import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "@oh-my-pi/pi-catalog/discovery/cursor-gen/agent_pb";
+import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, PiBashExecArgs, PiBashExecResult, PiEditExecArgs, PiEditExecResult, PiFindExecArgs, PiFindExecResult, PiGrepExecArgs, PiGrepExecResult, PiLsExecArgs, PiLsExecResult, PiReadExecArgs, PiReadExecResult, PiWriteExecArgs, PiWriteExecResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "@oh-my-pi/pi-catalog/discovery/cursor-gen/agent_pb";
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import type { Api, FetchImpl, Model, Provider, ThinkingBudgets, Usage } from "@oh-my-pi/pi-catalog/types";
 import type { Type } from "arktype";
@@ -754,6 +754,14 @@ export interface CursorMcpCall {
     toolCallId: string;
     args: Record<string, unknown>;
     rawArgs: Record<string, Uint8Array>;
+    /**
+     * The frame asks only whether this call would be permitted — it must not
+     * run. The server sends it to resolve a smart-mode approval decision ahead
+     * of the real invocation, and answers with the dedicated `approved`
+     * variant, so executing here would fire a side-effecting tool the user has
+     * not yet been asked about (and fire it twice once the real call arrives).
+     */
+    approvalOnly?: boolean;
 }
 export interface CursorTodoSnapshotItem {
     content: string;
@@ -796,6 +804,51 @@ export interface CursorShellStreamCallbacks {
     onStdout(data: string): void;
     onStderr(data: string): void;
 }
+/**
+ * A modern Pi exec frame plus the call id the dispatcher minted for it.
+ *
+ * Unlike the legacy exec args (`ReadArgs`, `ShellArgs`, ...), the Pi frames
+ * carry no `tool_call_id` field: on modern builds the id rides the streamed
+ * `ToolCall` envelope (`ToolCall.tool_call_id = 57`) instead of each variant's
+ * args. The exec channel has no access to that envelope, so the dispatcher
+ * mints an id and hands it to the handler, keeping the synthesized transcript
+ * block and its paired `toolResult` on the same key.
+ */
+export interface CursorPiCall<TArgs> {
+    args: TArgs;
+    toolCallId: string;
+}
+/** One resource a host's MCP servers advertise. */
+export interface CursorMcpResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    /** The server advertising it; Cursor addresses reads by this name. */
+    server: string;
+}
+/**
+ * The content of one resource read.
+ *
+ * `text` and `blob` are the wire's content oneof: exactly one is sent, with
+ * `text` winning when a host supplies both. A download instead sets
+ * `downloadPath` and no content at all — the model is told where the file
+ * landed rather than being handed its bytes.
+ */
+export interface CursorMcpResourceContent {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    text?: string;
+    blob?: Uint8Array;
+    /**
+     * Where the host wrote the resource, workspace-relative, when the frame
+     * asked for a download. Set this INSTEAD of `text`/`blob`: the wire
+     * contract is that a download returns no content to the model.
+     */
+    downloadPath?: string;
+}
 export interface CursorExecHandlers {
     read?: (args: ReadArgs) => Promise<CursorExecHandlerResult<ReadResult>>;
     ls?: (args: LsArgs) => Promise<CursorExecHandlerResult<LsResult>>;
@@ -806,6 +859,53 @@ export interface CursorExecHandlers {
     shellStream?: (args: ShellArgs, callbacks: CursorShellStreamCallbacks) => Promise<CursorExecHandlerResult<ShellResult>>;
     diagnostics?: (args: DiagnosticsArgs) => Promise<CursorExecHandlerResult<DiagnosticsResult>>;
     mcp?: (call: CursorMcpCall) => Promise<CursorExecHandlerResult<McpResult>>;
+    /**
+     * Answers "would this MCP call be permitted", without running it.
+     *
+     * A modern `mcpArgs` frame carrying `smart_mode_approval_only` asks for the
+     * permission decision alone, ahead of the real invocation. Executing the
+     * tool to answer it would fire a side effect the user never approved — and
+     * fire it twice once the real call arrives.
+     *
+     * `true` only when the host's policy resolves to a definite allow. A pending
+     * prompt is `false`: it can only be answered interactively at execution
+     * time, and there is no "ask me later" reply in this frame's result. When no
+     * handler is registered the provider refuses, since it cannot decide.
+     */
+    mcpApprovalPreflight?: (call: CursorMcpCall) => Promise<boolean>;
+    /**
+     * Modern Cursor CLI Pi tool frames (`ExecServerMessage` 45-51). They are a
+     * distinct frame family from the legacy `readArgs`/`shellArgs`/... set, not
+     * an alias: different args, different result oneofs, and no `tool_call_id`.
+     */
+    piRead?: (call: CursorPiCall<PiReadExecArgs>) => Promise<CursorExecHandlerResult<PiReadExecResult>>;
+    piBash?: (call: CursorPiCall<PiBashExecArgs>) => Promise<CursorExecHandlerResult<PiBashExecResult>>;
+    piEdit?: (call: CursorPiCall<PiEditExecArgs>) => Promise<CursorExecHandlerResult<PiEditExecResult>>;
+    piWrite?: (call: CursorPiCall<PiWriteExecArgs>) => Promise<CursorExecHandlerResult<PiWriteExecResult>>;
+    piGrep?: (call: CursorPiCall<PiGrepExecArgs>) => Promise<CursorExecHandlerResult<PiGrepExecResult>>;
+    piFind?: (call: CursorPiCall<PiFindExecArgs>) => Promise<CursorExecHandlerResult<PiFindExecResult>>;
+    piLs?: (call: CursorPiCall<PiLsExecArgs>) => Promise<CursorExecHandlerResult<PiLsExecResult>>;
+    /**
+     * The resources the host's MCP servers advertise, optionally filtered to one
+     * server. Without a handler the provider answers an empty catalog, which
+     * hides resources a host is in fact holding live connections to.
+     */
+    listMcpResources?: (args: {
+        server?: string;
+    }) => Promise<CursorMcpResource[]>;
+    /**
+     * Read one resource. `null` means the server or uri is genuinely unknown,
+     * which the provider answers as `not_found`; throwing surfaces as `error`.
+     */
+    readMcpResource?: (args: {
+        server: string;
+        uri: string;
+        /**
+         * When set, write the resource here (workspace-relative) and return
+         * `downloadPath` instead of content.
+         */
+        downloadPath?: string;
+    }) => Promise<CursorMcpResourceContent | null>;
     /** Mirror Cursor's server-owned todo list into local session state. */
     todoSync?: CursorTodoSyncHandler;
     onToolResult?: CursorToolResultHandler;

package/dist/types/usage/umans.d.ts

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

package/dist/types/utils/block-symbols.d.ts

@@ -14,6 +14,17 @@ export declare function clearStreamingPartialJson(block: StreamingPartialJsonCar
 export declare const kStreamingBlockIndex: unique symbol;
 /** Stores the last parsed argument prefix length for throttled streaming JSON parsing. */
 export declare const kStreamingLastParseLen: unique symbol;
+/**
+ * The Cursor interaction envelope's `call_id` for a streamed tool-call block.
+ *
+ * Tracked separately from the block's own `id` because they are NOT the same
+ * key: MCP and Pi blocks are filed under the id inside the call's `args`, which
+ * is what the exec channel pairs its result under, while every streamed
+ * `ToolCall*Update` correlates on the envelope's `call_id`. Matching
+ * completions against the block id would mis-route every call whose args carry
+ * their own id.
+ */
+export declare const kStreamingEnvelopeId: unique symbol;
 /** Marks streamed tool-call arguments that already received an authoritative done payload. */
 export declare const kStreamingArgumentsDone: unique symbol;
 /** Classifies Cursor's in-flight tool-call kind without leaking provider-private state. */

package/dist/types/utils/harmony-leak.d.ts

@@ -1,13 +1,21 @@
+import type { AssistantMessage, Model, ToolCall } from "../types.js";
 /**
- * GPT-5 Harmony-header leakage detection and recovery.
+ * Escape reserved Harmony control tokens in arbitrary text so it can be
+ * transported as data to a harmony-dialect model. Returns the input unchanged
+ * when it carries no reserved spelling.
  *
- * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
- * implements §3 of that document: detection by signal fusion, plus a
- * truncate-and-resume primitive for the `edit` tool when its input is in
- * hashline DSL form. Other tools and surfaces fall through to
- * abort-and-retry handled by the agent loop.
+ * Callers MUST gate on a harmony target and escape only the transport copy —
+ * the persisted transcript keeps the byte-for-byte original.
  */
-import type { AssistantMessage, Model, ToolCall } from "../types.js";
+export declare function escapeHarmonyControlTokens(text: string): string;
+/**
+ * Whether requests to `model` are served by a Harmony-dialect backend
+ * (gpt-5.x / gpt-oss), which rejects reserved control-token spellings appearing
+ * as data in the request. Resolves the wire model id (`requestModelId ?? id`)
+ * so deployment/catalog aliases — e.g. an Azure alias whose `requestModelId` is
+ * `gpt-5.4` — are detected even when the local id is opaque.
+ */
+export declare function isHarmonyDialectModel(model: Model): boolean;
 declare const SIGNAL_ORDER: readonly ["M", "C", "G", "S", "B", "R", "T"];
 export type HarmonySignalClass = "H" | (typeof SIGNAL_ORDER)[number];
 export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";

package/dist/types/utils/schema/normalize.d.ts

@@ -26,6 +26,7 @@ export interface NormalizeSchemaOptions {
     inferTypeForBareEnum: boolean;
     foldOneOfIntoAnyOf: boolean;
     dropNonScalarEnum: boolean;
+    stringEnumsOnly?: boolean;
     rejectResidualIncompatibilities?: ReadonlyArray<ResidualSchemaIncompatibility>;
     validateAndFallback?: {
         fallback: unknown;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.1.8",
+	"version": "17.2.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.1.8",
-		"@oh-my-pi/pi-utils": "17.1.8",
-		"@oh-my-pi/pi-wire": "17.1.8",
+		"@oh-my-pi/pi-catalog": "17.2.0",
+		"@oh-my-pi/pi-utils": "17.2.0",
+		"@oh-my-pi/pi-wire": "17.2.0",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},

package/src/auth-broker/client.ts

@@ -28,6 +28,7 @@ import type {
 	UsageResponse,
 	UsageStaleResponse,
 } from "./types";
+import { AUTH_BROKER_CAPABILITIES_HEADER, AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES } from "./types";
 import { getAuthBrokerWireSchemas } from "./wire-schema-resource";
 
 type AuthBrokerResponseSchemaName =
@@ -135,7 +136,9 @@ export class AuthBrokerClient {
 		const query = new URLSearchParams();
 		if (opts.waitMs !== undefined) query.set("wait", String(opts.waitMs));
 		const path = `/v1/snapshot${query.size > 0 ? `?${query.toString()}` : ""}`;
-		const headers: Record<string, string> = {};
+		const headers: Record<string, string> = {
+			[AUTH_BROKER_CAPABILITIES_HEADER]: AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES,
+		};
 		if (opts.ifGenerationGt !== undefined) headers["If-None-Match"] = `"${opts.ifGenerationGt}"`;
 		const timeoutMs =
 			opts.waitMs !== undefined && opts.waitMs > 0 ? Math.max(this.#timeoutMs, opts.waitMs + 1000) : undefined;
@@ -176,6 +179,7 @@ export class AuthBrokerClient {
 		const headers: Record<string, string> = {
 			Accept: "text/event-stream",
 			Authorization: `Bearer ${this.#token}`,
+			[AUTH_BROKER_CAPABILITIES_HEADER]: AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES,
 		};
 		if (opts.signal?.aborted) {
 			throw new AuthBrokerError("Auth broker request aborted", { cause: opts.signal.reason });

package/src/auth-broker/server.ts

@@ -32,6 +32,8 @@ import type {
 	SnapshotStreamSnapshotEvent,
 } from "./types";
 import {
+	AUTH_BROKER_CAPABILITIES_HEADER,
+	AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES,
 	DEFAULT_AUTH_BROKER_BIND,
 	DEFAULT_REFRESH_INTERVAL_MS,
 	DEFAULT_REFRESH_SKEW_MS,
@@ -40,6 +42,8 @@ import {
 } from "./types";
 import { getAuthBrokerWireSchemas } from "./wire-schema-resource";
 
+const DEFAULT_EXTERNAL_CHANGE_POLL_MS = 250;
+
 export interface AuthBrokerServerOptions {
 	/** Underlying credential storage (wraps the local SQLite store on the broker). */
 	storage: AuthStorage;
@@ -61,6 +65,11 @@ export interface AuthBrokerServerOptions {
 	 * without long sleeps. Default {@link DEFAULT_STREAM_KEEPALIVE_MS}.
 	 */
 	streamKeepaliveMs?: number;
+	/**
+	 * Override cross-process SQLite change polling in milliseconds.
+	 * Internal-only — tests use a short interval. Default 250ms.
+	 */
+	externalChangePollMs?: number;
 }
 
 export interface AuthBrokerServerHandle {
@@ -91,6 +100,15 @@ function isAuthorized(req: Request, tokens: ReadonlySet<string>): boolean {
 	return tokens.has(match[1].trim());
 }
 
+function supportsCodexMeterBlockScopes(req: Request): boolean {
+	const capabilities = req.headers.get(AUTH_BROKER_CAPABILITIES_HEADER);
+	return (
+		capabilities
+			?.split(",")
+			.some(capability => capability.trim() === AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES) ?? false
+	);
+}
+
 /**
  * Parse + validate a JSON request body against an ArkType schema. Returns a
  * `Response` (400) on parse/validation failure so handlers can early-return.
@@ -135,6 +153,7 @@ function snapshotHeaders(generation: number): Record<string, string> {
 	return {
 		ETag: `"${generation}"`,
 		"Cache-Control": "no-store",
+		Vary: AUTH_BROKER_CAPABILITIES_HEADER,
 	};
 }
 
@@ -171,11 +190,18 @@ function delayResult(ms: number): { promise: Promise<"timeout">; cancel: () => v
 class GenerationGate {
 	readonly #storage: AuthStorage;
 	readonly #unsubscribe: () => void;
+	readonly #pollTimer: NodeJS.Timeout;
+	#pollInFlight = false;
 	#waiters: Map<number, Set<() => void>> = new Map();
 
-	constructor(storage: AuthStorage) {
+	constructor(storage: AuthStorage, pollIntervalMs: number) {
 		this.#storage = storage;
 		this.#unsubscribe = storage.onGenerationChanged(generation => this.#wake(generation));
+		this.#pollTimer = setInterval(() => {
+			void this.#pollExternalChanges();
+		}, pollIntervalMs);
+		this.#pollTimer.unref?.();
+		void this.#pollExternalChanges();
 	}
 
 	waitForChange(afterGeneration: number, signal: AbortSignal): Promise<"changed" | "aborted"> {
@@ -207,6 +233,7 @@ class GenerationGate {
 	}
 
 	close(): void {
+		clearInterval(this.#pollTimer);
 		this.#unsubscribe();
 		for (const waiters of this.#waiters.values()) {
 			for (const resolve of waiters) resolve();
@@ -214,6 +241,18 @@ class GenerationGate {
 		this.#waiters.clear();
 	}
 
+	async #pollExternalChanges(): Promise<void> {
+		if (this.#pollInFlight) return;
+		this.#pollInFlight = true;
+		try {
+			await this.#storage.pollExternalChanges();
+		} catch (error) {
+			logger.debug("Auth broker external store change poll failed", { error: String(error) });
+		} finally {
+			this.#pollInFlight = false;
+		}
+	}
+
 	#wake(generation: number): void {
 		for (const [waitingFor, waiters] of [...this.#waiters]) {
 			if (generation <= waitingFor) continue;
@@ -277,9 +316,46 @@ function compareCredentialBlockSnapshots(a: CredentialBlockSnapshot, b: Credenti
 	return a.blockedUntilMs - b.blockedUntilMs;
 }
 
+const CODEX_BLOCK_PROVIDER_KEY = "openai-codex:oauth";
+const CODEX_LEGACY_PROJECTED_BLOCK_SCOPES = new Set(["chat", "spark", "shared"]);
+
+/**
+ * Older clients only consult the Codex `shared` scope. Keep SQLite canonical
+ * state meter-scoped, but conservatively collapse those scopes on their wire
+ * view so any active meter block remains visible to them.
+ */
+function projectCredentialBlocksForLegacyClient(blocks: readonly CredentialBlockSnapshot[]): CredentialBlockSnapshot[] {
+	const projected: CredentialBlockSnapshot[] = [];
+	let shared: CredentialBlockSnapshot | undefined;
+	for (const block of blocks) {
+		if (
+			block.providerKey !== CODEX_BLOCK_PROVIDER_KEY ||
+			!CODEX_LEGACY_PROJECTED_BLOCK_SCOPES.has(block.blockScope)
+		) {
+			projected.push(block);
+			continue;
+		}
+		const updatedAtMs =
+			block.updatedAtMs === undefined
+				? shared?.updatedAtMs
+				: shared?.updatedAtMs === undefined
+					? block.updatedAtMs
+					: Math.max(shared.updatedAtMs, block.updatedAtMs);
+		shared = {
+			providerKey: CODEX_BLOCK_PROVIDER_KEY,
+			blockScope: "shared",
+			blockedUntilMs: Math.max(shared?.blockedUntilMs ?? 0, block.blockedUntilMs),
+			...(updatedAtMs !== undefined ? { updatedAtMs } : {}),
+		};
+	}
+	if (shared) projected.push(shared);
+	return projected;
+}
+
 function buildCredentialBlockGroups(
 	blocks: readonly StoredCredentialBlock[],
 	serverNowMs: number,
+	clientSupportsCodexMeterBlockScopes: boolean,
 ): Map<number, CredentialBlockSnapshot[]> {
 	const byCredentialId = new Map<number, CredentialBlockSnapshot[]>();
 	for (const block of blocks) {
@@ -297,16 +373,30 @@ function buildCredentialBlockGroups(
 			byCredentialId.set(block.credentialId, [snapshotBlock]);
 		}
 	}
-	for (const credentialBlocks of byCredentialId.values()) credentialBlocks.sort(compareCredentialBlockSnapshots);
+	for (const [credentialId, credentialBlocks] of byCredentialId) {
+		const projected = clientSupportsCodexMeterBlockScopes
+			? credentialBlocks
+			: projectCredentialBlocksForLegacyClient(credentialBlocks);
+		projected.sort(compareCredentialBlockSnapshots);
+		byCredentialId.set(credentialId, projected);
+	}
 	return byCredentialId;
 }
 
-function buildSnapshot(storage: AuthStorage, refresher: AuthBrokerRefresher | undefined): SnapshotResponse {
+function buildSnapshot(
+	storage: AuthStorage,
+	refresher: AuthBrokerRefresher | undefined,
+	clientSupportsCodexMeterBlockScopes: boolean,
+): SnapshotResponse {
 	const serverNowMs = Date.now();
 	const base = storage.exportSnapshot();
 	const { wire, nextSweepAt } = resolveRefresherSchedule(refresher, serverNowMs);
 	const credentialIds = base.credentials.map(entry => entry.id);
-	const blocksByCredentialId = buildCredentialBlockGroups(storage.listCredentialBlocks(credentialIds), serverNowMs);
+	const blocksByCredentialId = buildCredentialBlockGroups(
+		storage.listCredentialBlocks(credentialIds),
+		serverNowMs,
+		clientSupportsCodexMeterBlockScopes,
+	);
 	const credentials: SnapshotEntry[] = base.credentials.map(entry => {
 		const blocks = blocksByCredentialId.get(entry.id);
 		const rotatesInMs = computeRotatesInMs(entry, wire, nextSweepAt, serverNowMs);
@@ -330,12 +420,13 @@ async function serveSnapshot(
 	peer: string,
 ): Promise<Response> {
 	await storage.reload();
+	const clientSupportsCodexMeterBlockScopes = supportsCodexMeterBlockScopes(req);
 	let currentGeneration = storage.getGeneration();
 	const clientGeneration = parseGenerationTag(req.headers.get("if-none-match"));
 	const waitMs = parseWaitMs(url);
 
 	if (clientGeneration === undefined || currentGeneration !== clientGeneration || waitMs <= 0) {
-		const body = buildSnapshot(storage, refresher);
+		const body = buildSnapshot(storage, refresher, clientSupportsCodexMeterBlockScopes);
 		logger.info("auth-broker snapshot served", {
 			peer,
 			credentials: body.credentials.length,
@@ -355,7 +446,7 @@ async function serveSnapshot(
 	await storage.reload();
 	currentGeneration = storage.getGeneration();
 	if (currentGeneration !== clientGeneration) {
-		const body = buildSnapshot(storage, refresher);
+		const body = buildSnapshot(storage, refresher, clientSupportsCodexMeterBlockScopes);
 		logger.info("auth-broker snapshot long-poll changed", {
 			peer,
 			credentials: body.credentials.length,
@@ -401,6 +492,7 @@ function serveSnapshotStream(
 ): Response {
 	const encoder = new TextEncoder();
 	const openedAt = Date.now();
+	const clientSupportsCodexMeterBlockScopes = supportsCodexMeterBlockScopes(req);
 	const lastByCredId = new Map<number, string>();
 	let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
 	let unsubscribe: (() => void) | null = null;
@@ -458,7 +550,7 @@ function serveSnapshotStream(
 				pendingBumps = 0;
 				await storage.reload();
 				if (closed) return;
-				const snapshot = buildSnapshot(storage, refresher);
+				const snapshot = buildSnapshot(storage, refresher, clientSupportsCodexMeterBlockScopes);
 				// Generation must move forward; a duplicate listener firing without a
 				// real bump is a no-op below (fingerprints unchanged).
 				if (snapshot.generation < lastGeneration) {
@@ -513,7 +605,7 @@ function serveSnapshotStream(
 		async start(c) {
 			controller = c;
 			await storage.reload();
-			const initial = buildSnapshot(storage, refresher);
+			const initial = buildSnapshot(storage, refresher, clientSupportsCodexMeterBlockScopes);
 			lastGeneration = initial.generation;
 			for (const entry of initial.credentials) lastByCredId.set(entry.id, fingerprintEntry(entry));
 			const initialEvent: SnapshotStreamSnapshotEvent = { kind: "snapshot", ...initial };
@@ -541,6 +633,7 @@ function serveSnapshotStream(
 			"Cache-Control": "no-cache",
 			Connection: "keep-alive",
 			"X-Accel-Buffering": "no",
+			Vary: AUTH_BROKER_CAPABILITIES_HEADER,
 		},
 	});
 }
@@ -551,6 +644,7 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 	const tokens = new Set<string>(opts.bearerTokens);
 	const version = opts.version;
 	const streamKeepaliveMs = opts.streamKeepaliveMs ?? DEFAULT_STREAM_KEEPALIVE_MS;
+	const externalChangePollMs = opts.externalChangePollMs ?? DEFAULT_EXTERNAL_CHANGE_POLL_MS;
 
 	const refresher = opts.disableRefresher
 		? undefined
@@ -560,7 +654,7 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 				refreshIntervalMs: opts.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS,
 			});
 	refresher?.start();
-	const generationGate = new GenerationGate(opts.storage);
+	const generationGate = new GenerationGate(opts.storage, externalChangePollMs);
 
 	const server = Bun.serve({
 		hostname: bind.hostname,

package/src/auth-broker/snapshot-cache.ts

@@ -12,7 +12,7 @@ import { isEnoent, logger } from "@oh-my-pi/pi-utils";
 import type { SnapshotResponse } from "./types";
 
 const MAGIC = new Uint8Array([0x4f, 0x4d, 0x50, 0x53]); // "OMPS"
-const VERSION = 1;
+const VERSION = 2;
 const VERSION_OFFSET = MAGIC.byteLength;
 const IV_OFFSET = VERSION_OFFSET + 1;
 const IV_LENGTH = 12;
@@ -118,7 +118,7 @@ async function encryptCachePayload(snapshot: SnapshotResponse, token: string, ur
 			{
 				name: AES_ALGORITHM,
 				iv,
-				additionalData: TEXT_ENCODER.encode(url),
+				additionalData: cacheAdditionalData(url),
 			},
 			key,
 			plaintext,
@@ -156,7 +156,7 @@ async function decryptCachePayload(data: Uint8Array, token: string, url: string)
 				{
 					name: AES_ALGORITHM,
 					iv,
-					additionalData: TEXT_ENCODER.encode(url),
+					additionalData: cacheAdditionalData(url),
 				},
 				key,
 				ciphertext,
@@ -168,6 +168,15 @@ async function decryptCachePayload(data: Uint8Array, token: string, url: string)
 	}
 }
 
+function cacheAdditionalData(url: string): Uint8Array<ArrayBuffer> {
+	const urlBytes = TEXT_ENCODER.encode(url);
+	const additionalData = new Uint8Array(IV_OFFSET + urlBytes.byteLength);
+	additionalData.set(MAGIC, 0);
+	additionalData[VERSION_OFFSET] = VERSION;
+	additionalData.set(urlBytes, IV_OFFSET);
+	return additionalData;
+}
+
 async function deriveAesKey(token: string, usages: Array<"encrypt" | "decrypt">): Promise<CryptoKey> {
 	const digest = await globalThis.crypto.subtle.digest("SHA-256", TEXT_ENCODER.encode(token));
 	return globalThis.crypto.subtle.importKey("raw", digest, AES_ALGORITHM, false, usages);

package/src/auth-broker/types.ts

@@ -165,6 +165,12 @@ export type SnapshotStreamEvent = SnapshotStreamSnapshotEvent | SnapshotStreamEn
  */
 export const AUTH_BROKER_API_PREFIX = "/v1";
 
+/** Request header used by clients to advertise optional auth-broker protocol features. */
+export const AUTH_BROKER_CAPABILITIES_HEADER = "OMP-Auth-Broker-Capabilities";
+
+/** Client understands independent Codex `chat` and `spark` credential-block scopes. */
+export const AUTH_BROKER_CAPABILITY_CODEX_METER_BLOCK_SCOPES = "codex-meter-block-scopes";
+
 /** Default port when none is configured. Loopback-only, no external exposure. */
 export const DEFAULT_AUTH_BROKER_BIND = "127.0.0.1:8765";