@zgltyq/pi-provider-claude 1.1.0 → 1.3.0

package/README.md

@@ -78,6 +78,33 @@ fail over between them: when the active account hits its rate / usage cap (429/5
 it's put on cooldown and the next turn transparently continues on the other account.
 Subscription billing is preserved (Pi detects the OAuth path from the token shape).
 
+**Priority:** array order in `claude-pool.json` IS the priority. `accounts[0]` is the
+primary — failover is non-sticky, so as soon as the primary's cooldown expires the
+pool returns to it automatically. Put your preferred account first.
+
+**Detection (v1.2.0):** pi-ai's anthropic transport only emits
+`after_provider_response` for *successful* requests — the Anthropic SDK throws on
+429/529 before that callback runs, so header-based detection alone never fires.
+Since v1.2.0 the primary detector pattern-matches the provider error that lands on
+the assistant message (`stopReason: "error"`) via `message_end`, including Claude's
+`"usage limit reached|<epoch>"` reset timestamps for accurate cooldowns. When a cap
+is hit, the turn errors once, the pool flips (with a UI notification), and you just
+resend your message to continue on the other account.
+
+**Background token refresh (v1.3.0):** OAuth access tokens are short-lived. An
+account that sat idle (e.g. your fallback) would have a dead access token by the
+time failover switched to it — producing a `401 authentication_error`. v1.3.0 adds:
+
+- A `setInterval` keep-warm loop that refreshes **every** pooled account before it
+  expires, even when idle and not the active account (the timer is `unref()`'d so
+  it never blocks CLI commands like `pi update` from exiting).
+- A wider 5-minute pre-expiry refresh buffer, and a full-pool refresh on
+  `session_start` / `before_agent_start` (not just the active account).
+- Reactive 401 handling: if the server rejects the active token anyway, it is
+  force-refreshed in place (no account switch) so the resend succeeds. If the
+  refresh token itself was revoked, you're told to re-run `/login` +
+  `/claude-pool-add <label>`.
+
 It is **inert** unless `<agentDir>/claude-pool.json` exists with ≥2 accounts and
 `"enabled" !== false`.
 

package/index.ts

@@ -291,12 +291,20 @@ const POOL_PATH = join(
 	process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"),
 	"claude-pool.json",
 );
-const POOL_REFRESH_BUFFER_MS = 60_000;
+// Refresh an access token this long BEFORE it actually expires, so we never
+// hand a request a token that's about to die. Generous because OAuth access
+// tokens are short-lived and the failover target may have sat idle for days.
+const POOL_REFRESH_BUFFER_MS = 5 * 60_000;
 const POOL_DEFAULT_COOLDOWN_MS = 5 * 60_000;
+// Background keep-warm cadence: re-check every account on this interval even
+// when idle / not the active one, so an account is never stale when we switch.
+const POOL_BG_REFRESH_INTERVAL_MS = 4 * 60_000;
 
 let poolAccounts: PoolAccount[] = [];
 let poolActive = 0;
 let poolCooldownUntil: number[] = [];
+let poolBgTimer: ReturnType<typeof setInterval> | undefined;
+let poolRefreshInFlight = false;
 
 function poolLog(msg: string): void {
 	writeDebugLog({ stage: "pool", time: new Date().toISOString(), msg });
@@ -336,7 +344,10 @@ function persistPool(): void {
 
 function poolSelectActive(): void {
 	const now = Date.now();
-	if (poolCooldownUntil[poolActive] <= now) return; // active still usable
+	// Priority = array order: always prefer the LOWEST-index account that is
+	// not cooling down (accounts[0] is the primary, e.g. "work"). This makes
+	// failover non-sticky: as soon as the primary's cooldown expires, we
+	// return to it instead of staying on the fallback account.
 	let pick = -1;
 	for (let i = 0; i < poolAccounts.length; i++) {
 		if (poolCooldownUntil[i] <= now) {
@@ -360,9 +371,12 @@ function poolSelectActive(): void {
 	}
 }
 
-async function poolEnsureFresh(i: number): Promise<void> {
+// Low-level refresh of account `i`. Returns true on success. When `force` is
+// false it skips accounts whose token is still comfortably valid.
+async function poolRefreshAccount(i: number, force: boolean): Promise<boolean> {
 	const acct = poolAccounts[i];
-	if (!acct || acct.expires > Date.now() + POOL_REFRESH_BUFFER_MS) return;
+	if (!acct) return false;
+	if (!force && acct.expires > Date.now() + POOL_REFRESH_BUFFER_MS) return true;
 	try {
 		const oauth = (await import("@earendil-works/pi-ai/oauth")) as {
 			refreshAnthropicToken: (
@@ -374,11 +388,39 @@ async function poolEnsureFresh(i: number): Promise<void> {
 		acct.expires = next.expires;
 		if (next.refresh) acct.refresh = next.refresh;
 		persistPool();
-		poolLog(`refreshed ${acct.label}`);
+		poolLog(`refreshed ${acct.label} (exp ${new Date(acct.expires).toISOString()})`);
+		return true;
 	} catch (e) {
 		poolLog(
 			`refresh FAILED ${acct.label}: ${(e as Error)?.message ?? String(e)}`,
 		);
+		return false;
+	}
+}
+
+// Refresh account `i` only if it is near (or past) expiry.
+async function poolEnsureFresh(i: number): Promise<void> {
+	await poolRefreshAccount(i, false);
+}
+
+// Force a refresh of account `i` regardless of expiry (used on a 401, when the
+// server rejected the token even though we thought it was still valid).
+async function poolForceRefresh(i: number): Promise<boolean> {
+	return poolRefreshAccount(i, true);
+}
+
+// Background keep-warm: refresh EVERY pooled account whose token is near expiry,
+// not just the active one. This is what guarantees the failover target is never
+// stale when we switch to it after it sat unused for a long time.
+async function poolRefreshAll(): Promise<void> {
+	if (poolRefreshInFlight) return; // never overlap refresh sweeps
+	poolRefreshInFlight = true;
+	try {
+		for (let i = 0; i < poolAccounts.length; i++) {
+			await poolEnsureFresh(i);
+		}
+	} finally {
+		poolRefreshInFlight = false;
 	}
 }
 
@@ -391,6 +433,10 @@ function poolMarkRateLimited(headers?: Record<string, string>): void {
 		const n = Number(ra);
 		if (Number.isFinite(n)) until = n > 1e9 ? n * 1000 : now + n * 1000; // epoch-seconds vs delta-seconds
 	}
+	poolMarkRateLimitedUntil(until);
+}
+
+function poolMarkRateLimitedUntil(until: number): void {
 	poolCooldownUntil[poolActive] = until;
 	poolLog(
 		`rate-limited ${poolAccounts[poolActive].label} until ${new Date(until).toISOString()}`,
@@ -398,6 +444,41 @@ function poolMarkRateLimited(headers?: Record<string, string>): void {
 	poolSelectActive();
 }
 
+// Rate/usage-cap detection from ERROR MESSAGES.
+//
+// pi-ai's anthropic provider only invokes onResponse (→ after_provider_response)
+// for SUCCESSFUL requests — on a 429/529 the Anthropic SDK throws before that
+// callback, so the header-based hook above never sees rate limits in practice.
+// The thrown error instead lands on the assistant message as stopReason:"error"
+// + errorMessage, which flows through message_end. We pattern-match it there.
+const POOL_LIMIT_RE =
+	/\b429\b|\b529\b|rate[ _-]?limit|usage[ _-]?limit|overloaded_error|quota/i;
+
+// Expired / rejected credential detection (401). When the active account's
+// token is rejected we force-refresh it in place so the resend succeeds — this
+// is the symptom of switching to an account that sat idle until its access
+// token died. Anchored to avoid colliding with the 429 message.
+const POOL_AUTH_RE =
+	/authentication_error|invalid authentication credentials|\b401\b/i;
+
+// Claude subscription cap messages often carry a reset epoch after a pipe,
+// e.g. "Claude AI usage limit reached|1750000000".
+function poolParseResetEpoch(message: string): number | undefined {
+	const m = message.match(/\|(\d{9,13})\b/);
+	if (!m) return undefined;
+	const n = Number(m[1]);
+	return n > 1e12 ? n : n * 1000;
+}
+
+// Returns true if the error was a rate/usage cap and the pool reacted.
+function poolHandleErrorMessage(errorMessage: string): boolean {
+	if (!POOL_LIMIT_RE.test(errorMessage)) return false;
+	const until =
+		poolParseResetEpoch(errorMessage) ?? Date.now() + POOL_DEFAULT_COOLDOWN_MS;
+	poolMarkRateLimitedUntil(until);
+	return true;
+}
+
 // Read the current single-slot anthropic OAuth creds from auth.json.
 function readAnthropicAuth():
 	| { refresh: string; access: string; expires: number }
@@ -509,7 +590,9 @@ function setupPool(pi: ExtensionAPI): void {
 
 	const prep = async () => {
 		poolSelectActive();
-		await poolEnsureFresh(poolActive);
+		// Keep ALL accounts warm, not just the active one, so the failover target
+		// is ready the instant we switch to it.
+		await poolRefreshAll();
 	};
 	pi.on("session_start", async () => {
 		await prep();
@@ -518,7 +601,82 @@ function setupPool(pi: ExtensionAPI): void {
 		await prep();
 	});
 
-	// Observe rate/usage-cap responses → cooldown the active account + flip.
+	// Background keep-warm loop: refresh every account before it expires even
+	// while idle / not active. This is the core fix — the failover target is kept
+	// fresh continuously so it's never expired when we switch to it.
+	//
+	// unref() is CRITICAL: an active timer handle keeps the Node event loop alive
+	// and would prevent short-lived CLI commands (e.g. `pi update`) from exiting.
+	// We also do NOT fire an immediate refresh here — interactive sessions warm
+	// via session_start; firing at module load would add network I/O to the CLI
+	// path. The first tick lands one interval later, only in long-lived sessions.
+	poolBgTimer = setInterval(() => {
+		void poolRefreshAll();
+	}, POOL_BG_REFRESH_INTERVAL_MS);
+	if (typeof poolBgTimer.unref === "function") poolBgTimer.unref();
+
+	// PRIMARY rate/usage-cap detector: provider errors surface on the assistant
+	// message (stopReason "error"), not via after_provider_response (the SDK
+	// throws on 429/529 before pi-ai's onResponse callback runs).
+	pi.on("message_end", async (event, ctx) => {
+		try {
+			const model = ctx.model;
+			if (
+				!model ||
+				model.provider !== "anthropic" ||
+				!ctx.modelRegistry.isUsingOAuth(model)
+			)
+				return undefined;
+			const msg = event.message as {
+				role?: string;
+				stopReason?: string;
+				errorMessage?: string;
+			};
+			if (
+				msg.role !== "assistant" ||
+				msg.stopReason !== "error" ||
+				typeof msg.errorMessage !== "string"
+			)
+				return undefined;
+			const prev = poolAccounts[poolActive]?.label;
+
+			// 401 / expired-credential path: the server rejected the ACTIVE token.
+			// Force-refresh it in place (don't switch accounts) so the resend works.
+			if (
+				POOL_AUTH_RE.test(msg.errorMessage) &&
+				!POOL_LIMIT_RE.test(msg.errorMessage)
+			) {
+				const ok = await poolForceRefresh(poolActive);
+				ctx.ui.notify(
+					ok
+						? `Claude account "${prev}" had an expired token — refreshed it. Resend your message to continue.`
+						: `Claude account "${prev}" token is invalid and refresh FAILED — its refresh token was likely revoked. Run /login anthropic then /claude-pool-add ${prev}.`,
+					ok ? "info" : "warning",
+				);
+				return undefined;
+			}
+
+			if (!poolHandleErrorMessage(msg.errorMessage)) return undefined;
+			const next = poolAccounts[poolActive]?.label;
+			if (next !== prev) {
+				await poolEnsureFresh(poolActive);
+				ctx.ui.notify(
+					`Claude account "${prev}" hit its limit → switched to "${next}". Resend your message to continue.`,
+					"warning",
+				);
+			} else {
+				ctx.ui.notify(
+					`Claude account "${prev}" hit its limit and all pooled accounts are cooling down — retrying on the one that frees up soonest.`,
+					"warning",
+				);
+			}
+		} catch {
+			/* detection must never break the message path */
+		}
+		return undefined;
+	});
+
+	// Secondary detector (kept for transports that DO surface response headers).
 	pi.on("after_provider_response", (event: unknown) => {
 		try {
 			const e = event as {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgltyq/pi-provider-claude",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Claude (Anthropic OAuth/subscription) compatibility layer for pi-coding-agent — keeps ALL extension tools usable under the Claude subscription by mapping unknown flat tool names to mcp__pi__<name> on the wire instead of dropping them, plus optional multi-account failover. Self-contained fork of the tool half of @benvargas/pi-claude-code-use.",
   "author": "Leechael",
   "license": "MIT",