@zgltyq/pi-provider-claude 1.0.0 → 1.2.0

package/README.md

@@ -71,12 +71,71 @@ PI_CLAUDE_PROVIDER_DEBUG_LOG=/tmp/claude-provider.log pi
 In `/tmp/claude-provider.log`, the `"after"` payload's `tools[]` should show your
 extension tools as `mcp__pi__<name>` and **nothing dropped**.
 
+## Multi-account failover (opt-in)
+
+If you have **two subscription accounts** (e.g. personal + work), the extension can
+fail over between them: when the active account hits its rate / usage cap (429/529),
+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.
+
+It is **inert** unless `<agentDir>/claude-pool.json` exists with ≥2 accounts and
+`"enabled" !== false`.
+
+### Enroll accounts with the native `/login` (recommended)
+
+`/login anthropic` only keeps ONE credential (a second login overwrites the first),
+so the extension adds a command to snapshot each login into the pool:
+
+```
+/login anthropic          → sign in with account A
+/claude-pool-add personal → stash account A in the pool
+/login anthropic          → sign in with account B (overwrites auth.json — fine)
+/claude-pool-add work      → stash account B in the pool
+/claude-pool-status        → verify both are present
+```
+
+Restart, and failover activates. `/claude-pool-add <label>` only writes
+`claude-pool.json` (it never touches the request path).
+
+### Alternative: harvest via separate profiles
+
+```bash
+PI_CODING_AGENT_DIR=~/.pi-personal pi    # /login anthropic  (personal)
+PI_CODING_AGENT_DIR=~/.pi-work     pi    # /login anthropic  (work)
+./harvest-claude-pool.sh                 # writes ~/.pi/agent/claude-pool.json
+```
+
+`claude-pool.json` shape:
+
+```json
+{ "enabled": true, "accounts": [
+  { "label": "personal", "refresh": "...", "access": "...", "expires": 0 },
+  { "label": "work",     "refresh": "...", "access": "...", "expires": 0 }
+] }
+```
+
+Kill switch: `PI_CLAUDE_PROVIDER_POOL_DISABLE=1` (or `"enabled": false`).
+
 ## Environment variables
 
 | Variable | Effect |
 |---|---|
-| `PI_CLAUDE_PROVIDER_DEBUG_LOG=/path` | Append `before`/`after` payloads for debugging. |
+| `PI_CLAUDE_PROVIDER_DEBUG_LOG=/path` | Append `before`/`after`/`pool` events for debugging. |
 | `PI_CLAUDE_PROVIDER_DISABLE=1` | Pass all tools through with flat names (no renaming). Debug escape hatch. |
+| `PI_CLAUDE_PROVIDER_POOL_DISABLE=1` | Disable multi-account failover even if `claude-pool.json` exists. |
 
 ## How it differs from `@benvargas/pi-claude-code-use`
 

package/harvest-claude-pool.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Harvest both accounts' Anthropic OAuth creds (from two PI_CODING_AGENT_DIR
+# profiles) into ~/.pi/agent/claude-pool.json for pi-provider-claude failover.
+#
+# Prereq — log into each profile ONCE (interactive), in separate terminals:
+#   PI_CODING_AGENT_DIR=~/.pi-personal pi   # then: /login anthropic  (personal)
+#   PI_CODING_AGENT_DIR=~/.pi-work     pi   # then: /login anthropic  (work)
+set -euo pipefail
+P_PERSONAL="${1:-$HOME/.pi-personal/auth.json}"
+P_WORK="${2:-$HOME/.pi-work/auth.json}"
+OUT="$HOME/.pi/agent/claude-pool.json"
+python3 - "$P_PERSONAL" "$P_WORK" "$OUT" <<'PY'
+import json,sys,os
+def block(path,label):
+    if not os.path.exists(path): sys.exit(f"missing {path} — run /login anthropic in that profile first")
+    a=json.load(open(path)).get("anthropic")
+    if not a or "access" not in a or "refresh" not in a:
+        sys.exit(f"{path}: no anthropic OAuth creds (did you /login anthropic with a subscription account?)")
+    return {"label":label,"refresh":a["refresh"],"access":a["access"],"expires":a.get("expires",0)}
+personal, work, out = sys.argv[1], sys.argv[2], sys.argv[3]
+pool={"enabled":True,"accounts":[block(personal,"personal"),block(work,"work")]}
+os.makedirs(os.path.dirname(out),exist_ok=True)
+with open(out,"w") as f: json.dump(pool,f,indent=2)
+os.chmod(out,0o600)
+print(f"wrote {out} with {len(pool['accounts'])} accounts:",", ".join(x['label'] for x in pool['accounts']))
+PY

package/index.ts

@@ -36,7 +36,14 @@
  *   PI_CLAUDE_PROVIDER_DISABLE=1        → pass everything through flat (debug)
  */
 
-import { appendFileSync } from "node:fs";
+import {
+	appendFileSync,
+	existsSync,
+	readFileSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 // Prefix used to disguise flat tools as MCP tools. Kept short so
@@ -252,6 +259,387 @@ function writeDebugLog(payload: unknown): void {
 	}
 }
 
+// ════════════════════════════════════════════════════════════════════════════
+// Multi-account failover (OPT-IN)
+//
+// Inert unless <agentDir>/claude-pool.json exists with >=2 accounts and
+// "enabled" !== false. Kill switch: PI_CLAUDE_PROVIDER_POOL_DISABLE=1.
+//
+// Mechanism: override the anthropic provider's OAuth credential supply so the
+// per-request token is the *currently active* pooled account. On a 429/529
+// (rate / usage cap) the active account is put on cooldown and the pointer
+// flips to the other account, so the next turn uses it. Tokens are refreshed in
+// an async before_agent_start hook because getApiKey() is synchronous.
+//
+// Subscription billing is preserved: Pi's transport detects the OAuth path from
+// the token's SHAPE (isOAuthToken), so any genuine pooled OAuth token still gets
+// the Claude Code identity headers automatically.
+// ════════════════════════════════════════════════════════════════════════════
+
+interface PoolAccount {
+	label: string;
+	refresh: string;
+	access: string;
+	expires: number;
+}
+interface PoolConfig {
+	enabled?: boolean;
+	accounts: PoolAccount[];
+}
+
+const POOL_PATH = join(
+	process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"),
+	"claude-pool.json",
+);
+const POOL_REFRESH_BUFFER_MS = 60_000;
+const POOL_DEFAULT_COOLDOWN_MS = 5 * 60_000;
+
+let poolAccounts: PoolAccount[] = [];
+let poolActive = 0;
+let poolCooldownUntil: number[] = [];
+
+function poolLog(msg: string): void {
+	writeDebugLog({ stage: "pool", time: new Date().toISOString(), msg });
+}
+
+function loadPool(): boolean {
+	try {
+		if (!existsSync(POOL_PATH)) return false;
+		const cfg = JSON.parse(readFileSync(POOL_PATH, "utf-8")) as PoolConfig;
+		if (cfg.enabled === false) return false;
+		const accts = (cfg.accounts || []).filter(
+			(a) => a && a.refresh && a.access,
+		);
+		if (accts.length < 2) return false;
+		poolAccounts = accts;
+		poolCooldownUntil = accts.map(() => 0);
+		poolActive = 0;
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function persistPool(): void {
+	try {
+		writeFileSync(
+			POOL_PATH,
+			JSON.stringify({ enabled: true, accounts: poolAccounts }, null, 2),
+			{
+				mode: 0o600,
+			},
+		);
+	} catch {
+		/* persistence is best-effort */
+	}
+}
+
+function poolSelectActive(): void {
+	const now = Date.now();
+	// 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) {
+			pick = i;
+			break;
+		}
+	}
+	if (pick === -1) {
+		// all cooling down → pick the one that frees up soonest
+		let min = Number.POSITIVE_INFINITY;
+		for (let i = 0; i < poolCooldownUntil.length; i++) {
+			if (poolCooldownUntil[i] < min) {
+				min = poolCooldownUntil[i];
+				pick = i;
+			}
+		}
+	}
+	if (pick !== poolActive) {
+		poolActive = pick;
+		poolLog(`switched active → ${poolAccounts[poolActive].label}`);
+	}
+}
+
+async function poolEnsureFresh(i: number): Promise<void> {
+	const acct = poolAccounts[i];
+	if (!acct || acct.expires > Date.now() + POOL_REFRESH_BUFFER_MS) return;
+	try {
+		const oauth = (await import("@earendil-works/pi-ai/oauth")) as {
+			refreshAnthropicToken: (
+				r: string,
+			) => Promise<{ refresh?: string; access: string; expires: number }>;
+		};
+		const next = await oauth.refreshAnthropicToken(acct.refresh);
+		acct.access = next.access;
+		acct.expires = next.expires;
+		if (next.refresh) acct.refresh = next.refresh;
+		persistPool();
+		poolLog(`refreshed ${acct.label}`);
+	} catch (e) {
+		poolLog(
+			`refresh FAILED ${acct.label}: ${(e as Error)?.message ?? String(e)}`,
+		);
+	}
+}
+
+function poolMarkRateLimited(headers?: Record<string, string>): void {
+	const now = Date.now();
+	let until = now + POOL_DEFAULT_COOLDOWN_MS;
+	const ra =
+		headers?.["retry-after"] ?? headers?.["anthropic-ratelimit-unified-reset"];
+	if (ra) {
+		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()}`,
+	);
+	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;
+
+// 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 }
+	| undefined {
+	try {
+		const authPath = join(
+			process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent"),
+			"auth.json",
+		);
+		if (!existsSync(authPath)) return undefined;
+		const a = (
+			JSON.parse(readFileSync(authPath, "utf-8")) as { anthropic?: PoolAccount }
+		).anthropic;
+		if (!a || !a.access || !a.refresh) return undefined;
+		return { refresh: a.refresh, access: a.access, expires: a.expires ?? 0 };
+	} catch {
+		return undefined;
+	}
+}
+
+// Upsert an account (by label) into claude-pool.json. Returns total count.
+function poolUpsert(
+	label: string,
+	creds: { refresh: string; access: string; expires: number },
+): number {
+	let cfg: PoolConfig = { enabled: true, accounts: [] };
+	try {
+		if (existsSync(POOL_PATH))
+			cfg = JSON.parse(readFileSync(POOL_PATH, "utf-8")) as PoolConfig;
+	} catch {
+		/* start fresh on a corrupt file */
+	}
+	if (!Array.isArray(cfg.accounts)) cfg.accounts = [];
+	const entry: PoolAccount = { label, ...creds };
+	const idx = cfg.accounts.findIndex((x) => x.label === label);
+	if (idx >= 0) cfg.accounts[idx] = entry;
+	else cfg.accounts.push(entry);
+	cfg.enabled = cfg.enabled !== false;
+	writeFileSync(POOL_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+	return cfg.accounts.length;
+}
+
+// /login enrollment + inspection. Always registered (touches files only, not
+// the request path), so you can bootstrap the pool with the native /login.
+function setupPoolCommands(pi: ExtensionAPI): void {
+	const register = pi.registerCommand as unknown as (
+		name: string,
+		def: {
+			description: string;
+			handler: (
+				args: string,
+				ctx: { ui: { notify: (m: string, l?: string) => void } },
+			) => Promise<void>;
+		},
+	) => void;
+
+	register("claude-pool-add", {
+		description:
+			"Snapshot the current '/login anthropic' account into the Claude failover pool. Usage: /claude-pool-add <label>",
+		handler: async (args, ctx) => {
+			const label = (args || "").trim() || `account-${Date.now()}`;
+			const creds = readAnthropicAuth();
+			if (!creds) {
+				ctx.ui.notify(
+					"No anthropic OAuth creds in auth.json — run /login anthropic first.",
+					"warning",
+				);
+				return;
+			}
+			const n = poolUpsert(label, creds);
+			ctx.ui.notify(
+				`Added "${label}" to Claude pool (${n} account${n === 1 ? "" : "s"}). ${n >= 2 ? "Restart to activate failover." : "Now /login the other account and run this again."}`,
+				"info",
+			);
+		},
+	});
+
+	register("claude-pool-status", {
+		description: "Show the Claude failover pool accounts",
+		handler: async (_args, ctx) => {
+			if (!existsSync(POOL_PATH)) {
+				ctx.ui.notify(
+					"No claude-pool.json yet. Use /claude-pool-add <label> after /login.",
+					"info",
+				);
+				return;
+			}
+			try {
+				const cfg = JSON.parse(readFileSync(POOL_PATH, "utf-8")) as PoolConfig;
+				const lines = (cfg.accounts || []).map(
+					(a, i) =>
+						`  ${i}. ${a.label} (exp ${a.expires ? new Date(a.expires).toISOString() : "?"})`,
+				);
+				ctx.ui.notify(
+					`Claude pool (enabled=${cfg.enabled !== false}):\n${lines.join("\n") || "  (none)"}`,
+					"info",
+				);
+			} catch (e) {
+				ctx.ui.notify(`pool read error: ${(e as Error).message}`, "warning");
+			}
+		},
+	});
+}
+
+function setupPool(pi: ExtensionAPI): void {
+	if (process.env.PI_CLAUDE_PROVIDER_POOL_DISABLE === "1") return;
+	if (!loadPool()) return; // inert unless a valid claude-pool.json exists
+	poolLog(`pool active: ${poolAccounts.map((a) => a.label).join(", ")}`);
+
+	const prep = async () => {
+		poolSelectActive();
+		await poolEnsureFresh(poolActive);
+	};
+	pi.on("session_start", async () => {
+		await prep();
+	});
+	pi.on("before_agent_start", async () => {
+		await prep();
+	});
+
+	// 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;
+			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 {
+				status?: number;
+				statusCode?: number;
+				headers?: Record<string, string>;
+			};
+			const status = e.status ?? e.statusCode;
+			if (status === 429 || status === 529) poolMarkRateLimited(e.headers);
+		} catch {
+			/* observation only — never break the response path */
+		}
+		return undefined;
+	});
+
+	// Supply the active pooled account's token to Pi's Anthropic transport.
+	const register = pi.registerProvider as unknown as (
+		id: string,
+		cfg: unknown,
+	) => void;
+	register("anthropic", {
+		oauth: {
+			name: `Claude (pooled: ${poolAccounts.map((a) => a.label).join("+")})`,
+			async login(callbacks: unknown) {
+				const m = (await import("@earendil-works/pi-ai/oauth")) as {
+					anthropicOAuthProvider: { login: (c: unknown) => Promise<unknown> };
+				};
+				return m.anthropicOAuthProvider.login(callbacks);
+			},
+			async refreshToken(_creds: unknown) {
+				await poolEnsureFresh(poolActive);
+				const a = poolAccounts[poolActive];
+				return { refresh: a.refresh, access: a.access, expires: a.expires };
+			},
+			getApiKey(creds: { access?: string } | undefined) {
+				const a = poolAccounts[poolActive];
+				return (a && a.access) || creds?.access || "";
+			},
+		},
+	});
+}
+
 export default function piProviderClaude(pi: ExtensionAPI): void {
 	// mcp__pi__* → flat, before the agent loop resolves the tool.
 	pi.on("message_end", async (event, _ctx) => {
@@ -280,4 +668,8 @@ export default function piProviderClaude(pi: ExtensionAPI): void {
 		writeDebugLog({ stage: "after", payload: transformed });
 		return transformed;
 	});
+
+	// Multi-account failover.
+	setupPoolCommands(pi); // /claude-pool-add, /claude-pool-status (always available)
+	setupPool(pi); // failover provider override (active once >=2 accounts exist)
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zgltyq/pi-provider-claude",
-  "version": "1.0.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. Self-contained fork of the tool half of @benvargas/pi-claude-code-use.",
+  "version": "1.2.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",
   "repository": {
@@ -33,7 +33,8 @@
     "index.ts",
     "package.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "harvest-claude-pool.sh"
   ],
   "pi": {
     "extensions": [