@herbertgao/pi-extensions 2026.9.19 → 2026.10.0

package/node_modules/pi-multi-account/model-pins.ts

@@ -0,0 +1,36 @@
+/** Explicit routing preferences; never foreground selections or authorization for a cheaper tier. */
+import { mutateConfigFile } from "./config-file-transaction.ts";
+
+export function validModelPinScope(scope: string): boolean {
+	return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(scope);
+}
+
+export function normalizeModelPins(value: unknown): Record<string, string> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	return Object.fromEntries(Object.entries(value).filter(([scope, model]) =>
+		validModelPinScope(scope) && typeof model === "string" && model.trim().length > 0 &&
+		!/[\s\x00-\x1f]/.test(model.trim()),
+	).map(([scope, model]) => [scope, (model as string).trim()]));
+}
+
+/** Change only one group's pin through the shared extension configuration transaction. */
+export function persistModelPin(
+	path: string,
+	scope: string,
+	model: string | undefined,
+	canCommit: () => boolean = () => true,
+): Record<string, string> {
+	if (!validModelPinScope(scope) || (model !== undefined && normalizeModelPins({ [scope]: model })[scope] !== model)) {
+		throw new Error("invalid model pin");
+	}
+	const next = mutateConfigFile(path, disk => {
+		if (disk.pinnedModels !== undefined && (!disk.pinnedModels || typeof disk.pinnedModels !== "object" || Array.isArray(disk.pinnedModels))) {
+			throw new Error("pinnedModels must be an object");
+		}
+		const pins = { ...disk.pinnedModels };
+		if (model === undefined) delete pins[scope];
+		else pins[scope] = model;
+		return { pinnedModels: pins };
+	}, canCommit);
+	return normalizeModelPins(next.pinnedModels);
+}

package/node_modules/pi-multi-account/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-account",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "description": "Automatic multi-account failover & rotation for Pi Agent across Anthropic (Claude), OpenAI/ChatGPT Codex, Kimi For Coding, Cursor, Qwen/Alibaba, and Ollama. Auto-discovers authenticated accounts, grows the rotation on login, and drops accounts on logout, expiry, or quota/rate-limit errors",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,9 @@
     "provider-payload-stream.ts",
     "auth-file-transaction.ts",
     "state-file-transaction.ts",
+    "config-file-transaction.ts",
     "model-catalog.ts",
+    "model-pins.ts",
     "usage.ts",
     "cursor-bridge.ts",
     "cursor-model-name.ts",
@@ -78,13 +80,13 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-ai": "0.85.1",
-    "@types/node": "^22.20.1",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@types/node": "^22.20.4",
     "typescript": "^6.0.3"
   },
   "pi": {
@@ -93,7 +95,7 @@
     ]
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.14.0",
+    "@bufbuild/protobuf": "^2.15.0",
     "proper-lockfile": "4.1.2"
   },
   "overrides": {

package/node_modules/pi-multi-account/slot-proxy-auth.ts

@@ -28,6 +28,7 @@ import {
 } from "./cursor-bridge.ts";
 import {
 	needsChildFacingApiKey,
+	isPlaceholderFor,
 	placeholderKeyFor,
 	proxyFamilyFor,
 	type ProxyFamily,
@@ -67,7 +68,7 @@ export function isChildFacingPlaceholder(
 	entry: AuthBlob | undefined,
 	family: ProxyFamily,
 ): boolean {
-	return entry?.type === "api_key" && entry.key === placeholderKeyFor(family);
+	return entry?.type === "api_key" && isPlaceholderFor(family, entry.key);
 }
 
 export function isChildFacingPlaceholderForSlot(
@@ -75,7 +76,9 @@ export function isChildFacingPlaceholderForSlot(
 	slotId: string,
 ): boolean {
 	const key = childFacingPlaceholderKey(slotId);
-	return !!key && entry?.type === "api_key" && entry.key === key;
+	const family = proxyFamilyFor(slotId);
+	return !!key && entry?.type === "api_key" &&
+		(family ? isPlaceholderFor(family, entry.key) : entry.key === key);
 }
 
 /** What the parent should use for refresh/upstream: sidecar OAuth wins over a child-facing placeholder. */
@@ -101,6 +104,13 @@ export function applyShadowPlan(
 		return { auth: { ...auth }, sidecar: { ...sidecar }, changed: false };
 	}
 	const entry = auth[slotId];
+	const hidden = sidecar[slotId];
+	if (isChildFacingPlaceholderForSlot(entry, slotId) && entry?.key !== facing.key &&
+		hidden?.type === "oauth" && typeof hidden.access === "string" && hidden.access.length > 0) {
+		// Upgrade only a publication backed by the parent's actual OAuth blob. Never rewrite a
+		// user's real API key or replace the hidden credential with a placeholder during migration.
+		return { auth: { ...auth, [slotId]: facing }, sidecar: { ...sidecar }, changed: true };
+	}
 	if (entry?.type === "oauth" && typeof entry.access === "string" && entry.access.length > 0) {
 		return {
 			auth: { ...auth, [slotId]: facing },

package/node_modules/pi-multi-account/slot-proxy.ts

@@ -36,6 +36,14 @@
  */
 export const PROXY_PLACEHOLDER_KEY = "pi-multi-account-proxy";
 
+/**
+ * Non-secret Anthropic placeholder with the shape Pi's native transport recognizes as OAuth.
+ * Request identity, tool-name conversion and response mapping all depend on this marker; adding
+ * a Bearer header at the proxy is too late. The proxy replaces it with the real token on egress.
+ * The legacy generic placeholder remains recognizable for restoration during an upgrade.
+ */
+export const ANTHROPIC_PROXY_PLACEHOLDER_KEY = "sk-ant-oat01-pi-multi-account-proxy";
+
 /**
  * The `apiKey` published for a **Codex** slot.
  *
@@ -60,9 +68,10 @@ export const PROXY_PLACEHOLDER_JWT = [
 	"",
 ].join(".");
 
-/** Either published placeholder — neither is a credential, both mark "a child we published for". */
+/** Current or legacy published placeholder — none is a real credential. */
 export function isPublishedPlaceholder(value: string | undefined): boolean {
-	return value === PROXY_PLACEHOLDER_KEY || value === PROXY_PLACEHOLDER_JWT;
+	return value === PROXY_PLACEHOLDER_KEY || value === PROXY_PLACEHOLDER_JWT ||
+		value === ANTHROPIC_PROXY_PLACEHOLDER_KEY;
 }
 
 export type ProxyFamily = "anthropic" | "codex";
@@ -273,7 +282,14 @@ export function shapeUpstreamRequest(args: {
 		}
 	}
 
-	return { ok: true, url: `${base}${rest}`, headers };
+	// Image tools append these endpoints directly to the slot base; chat already sends /codex.
+	// Leave all other paths and families intact, including usage requests.
+	const upstreamRest =
+		route.family === "codex" && /^\/images\/(?:generations|edits)(?:\?.*)?$/.test(rest)
+			? `/codex${rest}`
+			: rest;
+
+	return { ok: true, url: `${base}${upstreamRest}`, headers };
 }
 
 /** Keep any beta flags the caller asked for, and add ours once. */
@@ -289,7 +305,13 @@ function mergeBeta(existing: string | undefined, required: string): string {
 
 /** The `apiKey` to publish for a slot of this family. */
 export function placeholderKeyFor(family: ProxyFamily): string {
-	return family === "codex" ? PROXY_PLACEHOLDER_JWT : PROXY_PLACEHOLDER_KEY;
+	return family === "codex" ? PROXY_PLACEHOLDER_JWT : ANTHROPIC_PROXY_PLACEHOLDER_KEY;
+}
+
+/** Recognize the previous Anthropic publication without mistaking real tokens for placeholders. */
+export function isPlaceholderFor(family: ProxyFamily, value: unknown): boolean {
+	return value === placeholderKeyFor(family) ||
+		(family === "anthropic" && value === PROXY_PLACEHOLDER_KEY);
 }
 
 /** The `models.json` route to publish for a slot served by this proxy. */
@@ -305,7 +327,7 @@ export function isOwnLoopbackPublication(
 	if (!existing || typeof existing !== "object") return false;
 	const rec = existing as Record<string, unknown>;
 	return (
-		rec.apiKey === placeholderKeyFor(family) &&
+		isPlaceholderFor(family, rec.apiKey) &&
 		typeof rec.baseUrl === "string" &&
 		rec.baseUrl.startsWith("http://127.0.0.1:")
 	);

package/node_modules/pi-web-access/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-09-30
+
+### Highlights
+
+- Tell the summarizer what matters to you, such as keeping prices, limits, and versions exactly as written.
+- Brave search holds up on low-rate plans instead of failing when several searches run at once.
+- OpenAI web search works when you signed in to Pi with your ChatGPT account.
+
+### Added
+
+- Add your own instructions to search summaries with `summaryInstructions` in `web-search.json`, for example "keep prices, limits, and versions verbatim." They apply to summaries from the curator and the `auto-summary` workflow, and the built-in safety rules still apply. Thanks to [@rcharrisg](https://github.com/rcharrisg) for [PR #489](https://github.com/nicobailon/pi-web-access/pull/489).
+
+### Fixed
+
+- Brave searches now wait their turn according to the rate limits Brave reports, so running several searches at once no longer overruns low-rate plans. If Brave says to slow down and the wait is short, the search retries once. If the wait is long, it fails right away and later searches respect the same wait. The 30-second search timeout includes this waiting. Thanks to [@saschaSpoonbill](https://github.com/saschaSpoonbill) for [PR #487](https://github.com/nicobailon/pi-web-access/pull/487).
+- OpenAI web search now works when you signed in to Pi with "Sign in with ChatGPT" on the `openai` provider. Searches go to OpenAI's official API, and `auto` search tries OpenAI first for this login, as it already did for `openai-codex`. With an `openai` API key, `auto` still tries Exa first. Thanks to [@kasumikira](https://github.com/kasumikira) for [issue #488](https://github.com/nicobailon/pi-web-access/issues/488).
+
 ## [0.34.0] - 2026-09-30
 
 ### Highlights

package/node_modules/pi-web-access/README.md

@@ -18,7 +18,7 @@
 
 **Video Understanding** — Point it at a YouTube video or local screen recording and ask questions about what's on screen. Full transcripts, visual descriptions, and frame extraction at exact timestamps.
 
-**Smart Fallbacks** — Every capability has a fallback chain. Search tries configured SearXNG first for local/private search. When the active Pi model is `openai-codex`, it then tries Codex-backed OpenAI search. Otherwise it tries Exa before OpenAI, then Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, Perplexity, Gemini API, and Gemini Web when browser cookies are enabled. YouTube tries Gemini Web when enabled, then API, then Perplexity. Blocked pages try configured self-hosted Firecrawl or Crawl4AI first. Third-party hosted page fetchers require explicit `fetchRouting.allowRemoteHostedProviders` opt-in for remote HTTP(S) targets.
+**Smart Fallbacks** — Every capability has a fallback chain. Search tries configured SearXNG first for local/private search. When the active Pi model uses a ChatGPT subscription (`openai-codex`, or `openai` with Sign in with ChatGPT), it then tries subscription-backed OpenAI search. Otherwise it tries Exa before OpenAI, then Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, Perplexity, Gemini API, and Gemini Web when browser cookies are enabled. YouTube tries Gemini Web when enabled, then API, then Perplexity. Blocked pages try configured self-hosted Firecrawl or Crawl4AI first. Third-party hosted page fetchers require explicit `fetchRouting.allowRemoteHostedProviders` opt-in for remote HTTP(S) targets.
 
 **GitHub Cloning** — GitHub URLs are cloned locally instead of scraped. The agent gets real file contents and a local path to explore, not rendered HTML.
 
@@ -47,7 +47,7 @@ Works immediately with no API keys — Exa MCP provides zero-config search. If P
 }
 ```
 
-In `auto` mode (default), `web_search` tries a configured SearXNG endpoint first for local/private search. When the active Pi model is `openai-codex`, it then tries Codex-backed OpenAI search. Otherwise it tries Exa (direct API if keyed, MCP if not) before OpenAI, then Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Perplexity, Gemini API, and Gemini Web when browser-cookie access is enabled. Exa handles search; curator summary drafts are generated separately by the configured Pi summary model, defaulting to Claude Haiku, Codex Luna, Codex Terra, Gemini 3.6 Flash, GPT-5 mini, then DeepSeek V4 Flash when available. Slow summary drafts fall back to a deterministic result summary after a bounded deadline.
+In `auto` mode (default), `web_search` tries a configured SearXNG endpoint first for local/private search. When the active Pi model uses a ChatGPT subscription (`openai-codex`, or `openai` with Sign in with ChatGPT), it then tries subscription-backed OpenAI search. Otherwise it tries Exa (direct API if keyed, MCP if not) before OpenAI, then Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Perplexity, Gemini API, and Gemini Web when browser-cookie access is enabled. Exa handles search; curator summary drafts are generated separately by the configured Pi summary model, defaulting to Claude Haiku, Codex Luna, Codex Terra, Gemini 3.6 Flash, GPT-5 mini, then DeepSeek V4 Flash when available. Slow summary drafts fall back to a deterministic result summary after a bounded deadline.
 
 For a third-party Responses-compatible gateway, set `openaiResponsesUrl` to its full Responses endpoint, or opt into reusing the selected Pi provider's base URL as described below. Without either opt-in, Pi credentials with a custom `baseUrl` are refused before sending a request, and availability checks mark OpenAI unavailable without blocking other providers. The auth-resolved base URL takes precedence over the model's; gateway Responses/`web_search` support is not inferred. An explicit endpoint overrides this guard, including an explicit official endpoint. Existing Codex subscription endpoint selection is preserved when provider URL reuse is not active.
 
@@ -190,7 +190,7 @@ web_search({ queries: ["query 1", "query 2"], workflow: "auto-summary" })
 | `includeContent` | Fetch full page content from sources in background |
 | `workflow` | `none` (skip curator; fresh-install default), `summary-review` (open curator and auto-generate a summary draft), or `auto-summary` (generate a summary without opening the curator) |
 
-Batch searches run up to three queries concurrently. Provider routing and fallback within each query remain sequential.
+Batch searches run up to three queries concurrently. Provider routing and fallback within each query remain sequential. Brave requests share an in-process queue and honor the rate-limit buckets returned in `X-RateLimit-*`; exhausted short windows delay the next request with a small safety margin, while long quota resets fail fast and keep the advertised cooldown active for later queued calls. HTTP 429 responses are retried once after the advertised `Retry-After` or rate-limit reset. Brave's 30-second search deadline covers queueing, cooldown waits, and both request attempts. The queue coordinates one Pi process; separate Pi processes still rely on Brave's 429 response.
 
 ### fetch_content
 
@@ -517,6 +517,7 @@ Config defaults to `~/.pi/agent/web-search.json` when neither `PI_CODING_AGENT_D
   "searchModel": "gemini-3.6-flash",
   "summaryModel": "anthropic/claude-haiku-4-5",
   "summaryGenerationDeadlineMs": 30000,
+  "summaryInstructions": "- Preserve concrete figures verbatim: prices, limits, versions, dates.\n- Name the product version each claim applies to.",
   "maxInlineContentChars": 30000,
   "workflow": "summary-review",
   "curatorTimeoutSeconds": 20,
@@ -571,6 +572,8 @@ Config defaults to `~/.pi/agent/web-search.json` when neither `PI_CODING_AGENT_D
 
 `summaryModel` accepts an optional thinking-level suffix, such as `anthropic/claude-haiku-4-5:low`. Supported suffixes are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
 
+`summaryInstructions` appends custom text to the Requirements section of the summary prompt used by the curator UI and `auto-summary` mode (e.g. `"- Preserve concrete figures verbatim: prices, limits, versions, dates.\n- Name the product version each claim applies to."`). The text is passed verbatim to the summary model, so use one `- ` bullet per requirement. It is additive: the built-in guardrails (no invented sources, explicit weak/conflicting-evidence notes, the Sources section) always stay in place, and curator regeneration feedback is still appended afterwards. Missing, non-string, or blank values leave the default prompt unchanged.
+
 All provider API-key fields (`openaiApiKey`, `braveApiKey`, `parallelApiKey`, `tinyfishApiKey`, `search1apiApiKey`, `searchinfinityApiKey`, `queritApiKey`, `tavilyApiKey`, `youApiKey`, `jinaApiKey`, `serpdiveApiKey`, `kagiApiKey`, `bochaApiKey`, `ollamaApiKey`, `valyuApiKey`, `serpbaseApiKey`, `serpapiApiKey`, `serperApiKey`, `serplyApiKey`, `baizhiApiKey`, `zaiApiKey`, `anysearchApiKey`, `xcrawlApiKey`, `xaiApiKey`, `mistralApiKey`, `brightdataApiKey`, `firecrawlApiKey`, `crawl4aiApiToken`, `exaApiKey`, `perplexityApiKey`, `geminiApiKey`, `datalabApiKey`, and `cloudflareApiKey`) accept explicit credential sources. Use `$NAME` or `${NAME}` to read one named environment variable, or prefix a trusted local shell command with `!` to resolve one value at provider request time. Escape `$$` as a literal leading `$` and `$!` as a literal leading `!`:
 
 ```json

package/node_modules/pi-web-access/brave-rate-limit.ts

@@ -0,0 +1,170 @@
+const DEFAULT_SAFETY_MARGIN_MS = 100;
+const DEFAULT_MAX_WAIT_MS = 30_000;
+
+export interface BraveRateLimitBucket {
+	limit: number;
+	windowSeconds: number | null;
+	remaining: number;
+	resetSeconds: number;
+}
+
+export interface BraveRateLimitCoordinatorOptions {
+	now?: () => number;
+	sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	safetyMarginMs?: number;
+	maxWaitMs?: number;
+}
+
+function parseNumberList(value: string | null): number[] {
+	if (!value) return [];
+	return value.split(",").map(part => Number(part.trim()));
+}
+
+function parsePolicyWindows(value: string | null): Array<number | null> {
+	if (!value) return [];
+	return value.split(",").map(part => {
+		const match = /(?:^|;)\s*w=(\d+(?:\.\d+)?)\s*(?:;|$)/i.exec(part.trim());
+		if (!match) return null;
+		const seconds = Number(match[1]);
+		return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+	});
+}
+
+/** Parse Brave's parallel rate-limit bucket headers by list position. */
+export function parseBraveRateLimitHeaders(headers: Headers): BraveRateLimitBucket[] {
+	const limits = parseNumberList(headers.get("x-ratelimit-limit"));
+	const remaining = parseNumberList(headers.get("x-ratelimit-remaining"));
+	const resets = parseNumberList(headers.get("x-ratelimit-reset"));
+	const windows = parsePolicyWindows(headers.get("x-ratelimit-policy"));
+	const count = Math.max(limits.length, remaining.length, resets.length, windows.length);
+	const buckets: BraveRateLimitBucket[] = [];
+
+	for (let index = 0; index < count; index++) {
+		const limit = limits[index];
+		const left = remaining[index];
+		const resetSeconds = resets[index];
+		if (![limit, left, resetSeconds].every(Number.isFinite) || limit < 0 || left < 0 || resetSeconds < 0) continue;
+		buckets.push({
+			limit,
+			windowSeconds: windows[index] ?? null,
+			remaining: left,
+			resetSeconds,
+		});
+	}
+	return buckets;
+}
+
+export function parseRetryAfterMs(headers: Headers, now = Date.now()): number | null {
+	const value = headers.get("retry-after")?.trim();
+	if (!value) return null;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+	const date = Date.parse(value);
+	if (!Number.isFinite(date)) return null;
+	return Math.max(0, date - now);
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return Promise.reject(new Error("Aborted"));
+	return new Promise((resolve, reject) => {
+		const cleanup = () => signal?.removeEventListener("abort", onAbort);
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			cleanup();
+			reject(new Error("Aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+function formatWait(ms: number): string {
+	const seconds = Math.ceil(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.ceil(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.ceil(minutes / 60);
+	return `${hours}h`;
+}
+
+export class BraveRateLimitCoordinator {
+	private queue: Promise<void> = Promise.resolve();
+	private blockedUntil = 0;
+	private readonly now: () => number;
+	private readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+	private readonly safetyMarginMs: number;
+	private readonly maxWaitMs: number;
+
+	constructor(options: BraveRateLimitCoordinatorOptions = {}) {
+		this.now = options.now ?? Date.now;
+		this.sleep = options.sleep ?? defaultSleep;
+		this.safetyMarginMs = options.safetyMarginMs ?? DEFAULT_SAFETY_MARGIN_MS;
+		this.maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+	}
+
+	run<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+		const scheduled = this.queue.then(async () => {
+			await this.waitForAvailability(signal);
+			if (signal?.aborted) throw new Error("Aborted");
+			return operation();
+		});
+		this.queue = scheduled.then(() => undefined, () => undefined);
+		if (!signal) return scheduled;
+		if (signal.aborted) return Promise.reject(new Error("Aborted"));
+		return new Promise<T>((resolve, reject) => {
+			const onAbort = () => reject(new Error("Aborted"));
+			signal.addEventListener("abort", onAbort, { once: true });
+			scheduled.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+		});
+	}
+
+	observe(headers: Headers): void {
+		const exhausted = parseBraveRateLimitHeaders(headers).filter(bucket => bucket.remaining === 0);
+		if (exhausted.length === 0) return;
+		const resetMs = Math.max(...exhausted.map(bucket => bucket.resetSeconds * 1000));
+		this.blockFor(resetMs);
+	}
+
+	retryDelay(headers: Headers): number | null {
+		const advertised = parseRetryAfterMs(headers, this.now());
+		const exhausted = parseBraveRateLimitHeaders(headers).filter(bucket => bucket.remaining === 0);
+		const bucketDelay = exhausted.length > 0
+			? Math.max(...exhausted.map(bucket => bucket.resetSeconds * 1000))
+			: null;
+		if (advertised === null && bucketDelay === null) return null;
+		return Math.max(advertised ?? 0, bucketDelay ?? 0) + this.safetyMarginMs;
+	}
+
+	recordRetryDelay(delayMs: number): void {
+		this.blockFor(delayMs, false);
+	}
+
+	async waitForRecordedCooldown(signal?: AbortSignal): Promise<void> {
+		await this.waitForAvailability(signal);
+	}
+
+	async waitForRetry(delayMs: number, signal?: AbortSignal): Promise<void> {
+		this.recordRetryDelay(delayMs);
+		await this.waitForRecordedCooldown(signal);
+	}
+
+	private blockFor(delayMs: number, addMargin = true): void {
+		const boundedDelay = Math.max(0, delayMs) + (addMargin ? this.safetyMarginMs : 0);
+		this.blockedUntil = Math.max(this.blockedUntil, this.now() + boundedDelay);
+	}
+
+	private async waitForAvailability(signal?: AbortSignal): Promise<void> {
+		const waitMs = Math.max(0, this.blockedUntil - this.now());
+		if (waitMs === 0) return;
+		this.assertWaitIsBounded(waitMs);
+		await this.sleep(waitMs, signal);
+	}
+
+	private assertWaitIsBounded(waitMs: number): void {
+		if (waitMs <= this.maxWaitMs) return;
+		throw new Error(`Brave Search quota exhausted; estimated reset in ${formatWait(waitMs)}. Refusing to wait longer than ${formatWait(this.maxWaitMs)} inside one search call.`);
+	}
+}

package/node_modules/pi-web-access/brave.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { activityMonitor } from "./activity.ts";
+import { BraveRateLimitCoordinator } from "./brave-rate-limit.ts";
 import { normalizeDomain } from "./domain-filter-normalization.ts";
 import { normalizeSearchResultCount } from "./search-result-count-normalization.ts";
 import type { SearchOptions, SearchResult, SearchResponse } from "./perplexity.ts";
@@ -9,6 +10,7 @@ import { fetchWithCredentialRedirects, getWebSearchConfigPath, resolveApiBaseUrl
 const BRAVE_API_BASE_URL = "https://api.search.brave.com/res/v1";
 const CONFIG_PATH = getWebSearchConfigPath();
 const SEARCH_TIMEOUT_MS = 30_000;
+const braveRateLimit = new BraveRateLimitCoordinator();
 
 interface WebSearchConfig {
 	braveApiKey?: unknown;
@@ -154,17 +156,32 @@ export async function searchWithBrave(
 	}
 
 	try {
-		const response = await fetchWithCredentialRedirects(`${apiUrl}?${params.toString()}`, {
-			method: "GET",
-			headers: {
-				"X-Subscription-Token": apiKey,
-				"Accept": "application/json",
-				"Accept-Encoding": "gzip",
-			},
-			signal: options.signal
-				? AbortSignal.any([AbortSignal.timeout(SEARCH_TIMEOUT_MS), options.signal])
-				: AbortSignal.timeout(SEARCH_TIMEOUT_MS),
-		}, ["X-Subscription-Token"]);
+		const searchDeadline = AbortSignal.timeout(SEARCH_TIMEOUT_MS);
+		const searchSignal = options.signal
+			? AbortSignal.any([searchDeadline, options.signal])
+			: searchDeadline;
+		const response = await braveRateLimit.run(async () => {
+			for (let attempt = 0; attempt < 2; attempt++) {
+				const current = await fetchWithCredentialRedirects(`${apiUrl}?${params.toString()}`, {
+					method: "GET",
+					headers: {
+						"X-Subscription-Token": apiKey,
+						"Accept": "application/json",
+						"Accept-Encoding": "gzip",
+					},
+					signal: searchSignal,
+				}, ["X-Subscription-Token"]);
+
+				braveRateLimit.observe(current.headers);
+				if (current.status !== 429 || attempt === 1) return current;
+				const retryDelay = braveRateLimit.retryDelay(current.headers);
+				if (retryDelay === null) return current;
+				braveRateLimit.recordRetryDelay(retryDelay);
+				await current.body?.cancel().catch(() => undefined);
+				await braveRateLimit.waitForRecordedCooldown(searchSignal);
+			}
+			throw new Error("Brave Search retry loop exited unexpectedly");
+		}, searchSignal);
 
 		if (!response.ok) {
 			activityMonitor.logError(activityId, `HTTP ${response.status}`);