pi-multikey 1.7.1 → 1.8.1

package/README.md

@@ -29,7 +29,7 @@ pi install /path/to/multikey
 /multikey → Add pool… → Preset: B.AI → paste keys one per line (blank line to finish)
 ```
 
-After picking the preset, the endpoint, compat, and all 6 model definitions are wired up automatically. Models are available directly as `bai/<model-id>`, e.g. `bai/deepseek-v4-flash`.
+After picking the preset, the endpoint, compat, and all 4 model definitions are wired up automatically. Models are available directly as `bai/<model-id>`, e.g. `bai/hy3`.
 
 ## Presets
 
@@ -37,8 +37,6 @@ Built-in presets decouple "model settings" from "keys". The data comes from b.ai
 
 | Model | ctx / max-out | Modalities | Supported thinking levels |
 |---|---|---|---|
-| deepseek-v4-flash | 1M / 384K | text | off · low · high · max |
-| deepseek-v4-flash-vision-exp | 1M / 384K | text+image | off · low · high · max |
 | hy3 | 256K / 128K | text | off · low · high |
 | mimo-v2.5 | 1M / 128K | text+image | off · high (official: low/medium/high behave identically) |
 | qwen3.8-flash | 1M / 131K | text+image | off · low · medium · xhigh |
@@ -46,27 +44,6 @@ Built-in presets decouple "model settings" from "keys". The data comes from b.ai
 
 > Why `null` must be explicit: pi's `getSupportedThinkingLevels` treats `mapped === null` as unsupported and hides that level, but **omitting** it is treated as supported and the level name is sent to the API verbatim; `xhigh` / `max` additionally require an explicit non-null value to be usable.
 
-### OpenCode Zen (free tier)
-
-Endpoint `https://opencode.ai/zen/v1`; keys from [opencode.ai/auth](https://opencode.ai/auth) → workspace Keys. Context / max-output are the **Zen free-tier serving limits** (consistent across models.dev `opencode` provider + pi's built-in opencode catalog); the raw models are bigger — MiMo V2.5 = 1M ctx, Hy3 = 262K ctx. `muse-spark-1.2-contributor-free` uses the OpenAI **Responses** API endpoint; the other seven use chat completions.
-
-Requests to this endpoint automatically carry the `User-Agent` header that opencode.ai expects (`opencode/1.15.0 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.13`) — appended whenever a pool's baseUrl is `https://opencode.ai/zen/v1`, on both probes and live requests.
-
-| Model | ctx / max-out | Modalities | Supported thinking levels |
-|---|---|---|---|
-| big-pickle | 200K / 32K | text | always-on (no thinkingLevelMap, like pi's catalog) |
-| deepseek-v4-flash-free | 200K / 128K | text | off · low · high · max (mirrors b.ai's deepseek-v4-flash) |
-| mimo-v2.5-free | 200K / 32K | text+image | always-on (no thinkingLevelMap) |
-| hy3-free | 190K / 64K | text | low · medium · high (no off) |
-| ling-3.0-flash-fin-free | 256K / 32K | text | always-on (no thinkingLevelMap) |
-| nemotron-3-ultra-free | 1M / 128K | text | always-on (no thinkingLevelMap) |
-| nemotron-3.5-lightning-free | 256K / 256K | text | always-on (no thinkingLevelMap) |
-| muse-spark-1.2-contributor-free | 1M / 128K | text+image | minimal · low · medium · high · xhigh (no off, Responses API) |
-
-> All eight models are free (zero per-token cost) for a limited time while OpenCode collects feedback; data may be used to improve the models (Nemotron free endpoints are NVIDIA trials — don't send confidential data).
-
-To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
-
 ## Configuration
 
 `~/.pi/agent/multikey.json`. On first run it auto-discovers mergeable pools from `~/.pi/agent/models.json` (≥2 providers sharing a baseUrl = you copying the provider per key), and also picks up providers pointing at `api.b.ai`; if nothing is found it generates an empty config.
@@ -75,7 +52,7 @@ To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
 {
   "pools": [
     {
-      "id": "bai",                          // provider id in pi → bai/deepseek-v4-flash
+      "id": "bai",                          // provider id in pi → bai/hy3
       "name": "B.AI (Key Pool)",
       "baseUrl": "https://api.b.ai/v1",
       "api": "openai-completions",
@@ -85,7 +62,9 @@ To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
       "invalidKeyCooldownMs": 600000,       // 401/403 cooldown
       "keys": [
         { "key": "sk-...", "label": "key-1", "enabled": true },
-        { "key": "sk-...", "label": "key-2", "enabled": true }
+        { "key": "sk-...", "label": "key-2", "enabled": true },
+        { "key": "<access token>", "label": "cline-account", "enabled": true,
+          "credential": { "kind": "cline-oauth", "refreshToken": "...", "accessToken": "...", "expiresAt": 1735689600000 } }
       ],
       "models": [ "…preset or hand-configured model definitions…" ]
     }
@@ -126,29 +105,15 @@ The detected header style is stored as `"auth": "api-key"` only when the endpoin
 
 Changes take effect immediately (the provider is re-registered) — no restart needed.
 
-## Pointing subagents at the pool
-
-Set `agentOverrides` in `settings.json` to the pool provider:
-
-```json
-"subagents": {
-  "agentOverrides": {
-    "oracle":   { "model": "bai/glm-5.3-flash" },
-    "scout":    { "model": "bai/hy3" },
-    "worker":   { "model": "bai/mimo-v2.5" }
-  }
-}
-```
-
-`defaultProvider: "bai"` works the same way.
-
 ## How it works
 
 - The extension registers a provider via `pi.registerProvider()` with a custom `streamSimple`.
 - Each request leases one key from the pool (`options.apiKey` overrides), and once the HTTP response headers arrive:
   - 429 → that key is cooled down (default 20s, honoring `retry-after`) and the request immediately retries with the next key (no duplicated output);
-  - 401/403 → that key gets a long cooldown (default 10 minutes) and the request retries with the next key;
+  - Cline daily free limit (429 + `"free limit reached on model"` in the body) → that key cools down until the server-reported reset time (hours, not seconds) and the request retries with the next key;
+  - 401/403 → that key gets a long cooldown (default 10 minutes) and the request retries with the next key; for OAuth-backed keys (Cline), a 401 first forces one token refresh + same-key retry before any cooldown;
   - other errors → handed back to pi's own retry mechanism.
+- OAuth-backed keys (Cline accounts) resolve a fresh access token from their stored refresh token before every request (single-flight per account, so concurrent subagents share one refresh), and every rotation of the refresh token is persisted back to `multikey.json`.
 - Only when every key is exhausted does it surface the 429 upward, letting pi's own backoff retry as a safety net (by then the earliest cooldown has usually expired).
 
 ## Security note

package/README.zh.md

@@ -27,8 +27,8 @@ pi install /path/to/multikey
 /multikey → Add pool… → Preset: B.AI → 逐行粘贴 key（一行一个，留空结束）
 ```
 
-选 preset 后 endpoint、compat、6 个模型的全部设定自动就位，模型通过
-`bai/<model-id>` 直接可用，例如 `bai/deepseek-v4-flash`。
+选 preset 后 endpoint、compat、4 个模型的全部设定自动就位，模型通过
+`bai/<model-id>` 直接可用，例如 `bai/hy3`。
 
 ## Presets
 
@@ -38,8 +38,6 @@ DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实
 
 | 模型 | ctx / max-out | 模态 | 生效 thinking 档位 |
 |---|---|---|---|
-| deepseek-v4-flash | 1M / 384K | text | off · low · high · max |
-| deepseek-v4-flash-vision-exp | 1M / 384K | text+image | off · low · high · max |
 | hy3 | 256K / 128K | text | off · low · high |
 | mimo-v2.5 | 1M / 128K | text+image | off · high（官方：low/medium/high 行为相同） |
 | qwen3.8-flash | 1M / 131K | text+image | off · low · medium · xhigh |
@@ -49,30 +47,6 @@ DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实
 > 视为不支持并隐藏该档，但**省略**会被当作支持并把档名原样发给 API；
 > `xhigh` / `max` 还要求显式给出非 null 值才可用。
 
-### OpenCode Zen（免费层）
-
-端点 `https://opencode.ai/zen/v1`；密钥从 [opencode.ai/auth](https://opencode.ai/auth) → workspace Keys 获取。
-上下文/最大输出为 **Zen 免费层限制**（models.dev `opencode` provider 与 pi 内置 opencode 目录一致）；
-原始模型更大——MiMo V2.5 = 1M ctx，Hy3 = 262K ctx。
-`muse-spark-1.2-contributor-free` 使用 OpenAI **Responses** API；其余七个使用 chat completions。
-
-对该端点的请求会自动携带 opencode.ai 期望的 `User-Agent` 头（`opencode/1.15.0 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.13`）——只要 pool 的 baseUrl 是 `https://opencode.ai/zen/v1`，探测和真实请求都会附加。
-
-| 模型 | ctx / max-out | 模态 | 生效 thinking 档位 |
-|---|---|---|---|
-| big-pickle | 200K / 32K | text | 始终思考（无 thinkingLevelMap，与 pi 内置目录一致） |
-| deepseek-v4-flash-free | 200K / 128K | text | off · low · high · max（沿用 b.ai preset 的 deepseek-v4-flash） |
-| mimo-v2.5-free | 200K / 32K | text+image | 始终思考（无 thinkingLevelMap） |
-| hy3-free | 190K / 64K | text | low · medium · high（无 off） |
-| ling-3.0-flash-fin-free | 256K / 32K | text | 始终思考（无 thinkingLevelMap） |
-| nemotron-3-ultra-free | 1M / 128K | text | 始终思考（无 thinkingLevelMap） |
-| nemotron-3.5-lightning-free | 256K / 256K | text | 始终思考（无 thinkingLevelMap） |
-| muse-spark-1.2-contributor-free | 1M / 128K | text+image | minimal · low · medium · high · xhigh（无 off，Responses API） |
-
-> 以上八个模型在 OpenCode 收集反馈期间均免费（零 token 费用）；数据可能用于改进模型（Nemotron 免费端点为 NVIDIA 试用——请勿提交机密数据）。
-
-新增 preset：在 `presets.ts` 的 `PRESETS` 数组里加一项即可。
-
 ## 配置
 
 `~/.pi/agent/multikey.json`。首次运行时会从 `~/.pi/agent/models.json` 自动发现
@@ -83,7 +57,7 @@ DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实
 {
   "pools": [
     {
-      "id": "bai",                          // pi 里的 provider id → bai/deepseek-v4-flash
+      "id": "bai",                          // pi 里的 provider id → bai/hy3
       "name": "B.AI (Key Pool)",
       "baseUrl": "https://api.b.ai/v1",
       "api": "openai-completions",
@@ -135,22 +109,6 @@ JSON 后 `Reload config from disk`。
 
 改动即时生效（重新注册 provider），无需重启。
 
-## 让 subagent 用上池
-
-`settings.json` 的 agentOverrides 改成池 provider：
-
-```json
-"subagents": {
-  "agentOverrides": {
-    "oracle":   { "model": "bai/glm-5.3-flash" },
-    "scout":    { "model": "bai/hy3" },
-    "worker":   { "model": "bai/mimo-v2.5" }
-  }
-}
-```
-
-`defaultProvider: "bai"` 同理。
-
 ## 工作原理
 
 - 扩展通过 `pi.registerProvider()` 注册 provider，并提供自定义 `streamSimple`。

package/cline-auth.ts

@@ -0,0 +1,293 @@
+/**
+ * Cline account authentication: WorkOS device flow + access token refresh.
+ *
+ * Cline's free models are tied to a Cline account (no static API keys), so a
+ * pool key can carry a `credential: { kind: "cline-oauth", refreshToken }`
+ * instead of a long-lived secret. Endpoints/port/response shapes are ported
+ * from the cline SDK (sdk/packages/core/src/auth/cline.ts, production env).
+ *
+ * Flow:
+ *   1. POST api.workos.com/user_management/authorize/device  → device + user code
+ *   2. User opens the verification URL in a browser and approves
+ *   3. Poll api.workos.com/user_management/authenticate      → WorkOS tokens
+ *   4. POST api.cline.bot/api/v1/auth/register               → Cline tokens
+ *   5. Refresh: POST api.cline.bot/api/v1/auth/refresh
+ *
+ * Tokens rotate on every refresh (the refresh token in the response replaces
+ * the old one), so callers must persist the result — stream.ts does this via
+ * KeyPool.applyClineCredential + the config save hook.
+ */
+
+import type { KeyCredential } from "./config.ts";
+
+const WORKOS_API_BASE_URL = "https://api.workos.com";
+const WORKOS_DEVICE_AUTHORIZATION_PATH = "/user_management/authorize/device";
+const WORKOS_AUTHENTICATE_PATH = "/user_management/authenticate";
+/** WorkOS client id of the official Cline CLI (production environment). */
+const WORKOS_CLIENT_ID = "client_01K3A541FN8TA3EPPHTD2325AR";
+
+const CLINE_API_BASE_URL = "https://api.cline.bot";
+const CLINE_REGISTER_PATH = "/api/v1/auth/register";
+const CLINE_REFRESH_PATH = "/api/v1/auth/refresh";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+const DEVICE_AUTH_EXPIRES_IN_SECONDS = 300;
+const DEVICE_AUTH_INTERVAL_SECONDS = 5;
+/** Refresh this long before expiry so requests never race the clock. */
+export const REFRESH_BUFFER_MS = 5 * 60_000;
+
+/** Headers sent to Cline API auth endpoints (same client identity as chat requests). */
+function clineAuthHeaders(): Record<string, string> {
+	return { "Content-Type": "application/json", "User-Agent": "Cline/3.0.61" };
+}
+
+export interface ClineTokenUpdate {
+	/** New access token (stored as the key's `key` value). */
+	accessToken: string;
+	/** Replacement refresh token; WorkOS/Cline rotate it on every refresh. */
+	refreshToken: string;
+	/** Access token expiry in epoch ms, when the server reports one. */
+	expiresAt?: number;
+}
+
+interface ClineTokenResponse {
+	success: boolean;
+	data?: {
+		accessToken?: string;
+		refreshToken?: string;
+		expiresAt?: string;
+	};
+}
+
+function parseExpiresAt(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const ms = Date.parse(value);
+	return Number.isFinite(ms) ? ms : undefined;
+}
+
+function requireClineTokens(payload: ClineTokenResponse, message: string): ClineTokenUpdate {
+	const accessToken = payload.data?.accessToken;
+	const refreshToken = payload.data?.refreshToken;
+	if (!payload.success || !accessToken || !refreshToken) {
+		throw new Error(message);
+	}
+	// Return the RAW token; the workos: prefix is applied at request time by
+	// formatClineAccessToken (idempotent), so it is never doubled.
+	return { accessToken, refreshToken, expiresAt: parseExpiresAt(payload.data?.expiresAt) };
+}
+
+/** True when the stored access token is missing, expired, or inside the refresh buffer. */
+export function isClineTokenStale(credential: KeyCredential, bufferMs = REFRESH_BUFFER_MS): boolean {
+	if (!credential.accessToken) return true;
+	if (credential.expiresAt === undefined) return false; // unknown expiry: use until a 401 says otherwise
+	return credential.expiresAt - Date.now() <= bufferMs;
+}
+
+/** Exchange a refresh token for a fresh access (+ rotated refresh) token. */
+export async function refreshClineToken(refreshToken: string): Promise<ClineTokenUpdate> {
+	const response = await fetch(`${CLINE_API_BASE_URL}${CLINE_REFRESH_PATH}`, {
+		method: "POST",
+		headers: clineAuthHeaders(),
+		body: JSON.stringify({ refreshToken, grantType: "refresh_token" }),
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+	});
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`Cline token refresh failed: HTTP ${response.status}${text ? ` — ${text.slice(0, 200)}` : ""}`);
+	}
+	const payload = (await response.json().catch(() => ({}))) as ClineTokenResponse;
+	return requireClineTokens(payload, "Invalid Cline token refresh response");
+}
+
+const WORKOS_ACCESS_TOKEN_PREFIX = "workos:";
+
+/**
+ * Cline's API requires the WorkOS access token prefixed with the literal
+ * string "workos:" in the Authorization header — the official client formats
+ * every stored access token this way before sending (formatAccessToken in
+ * cline core). A raw JWT gets a generic 401 that looks like a bad key.
+ */
+export function formatClineAccessToken(accessToken: string): string {
+	const token = accessToken.trim();
+	return token.toLowerCase().startsWith(WORKOS_ACCESS_TOKEN_PREFIX) ? token : `${WORKOS_ACCESS_TOKEN_PREFIX}${token}`;
+}
+
+// Single-flight per refresh token: concurrent subagents hitting the same
+// account must share one in-flight refresh instead of racing each other.
+const inFlight = new Map<string, Promise<ClineTokenUpdate>>();
+
+/**
+ * Return a usable access token for the credential, refreshing when stale.
+ * Pass `force` after a 401 to refresh even if the token looks valid.
+ */
+export async function ensureClineAccessToken(
+	credential: KeyCredential,
+	options?: { force?: boolean },
+): Promise<ClineTokenUpdate & { refreshed: boolean }> {
+	const force = options?.force === true;
+	if (!force && !isClineTokenStale(credential) && credential.accessToken) {
+		return {
+			accessToken: formatClineAccessToken(credential.accessToken),
+			refreshToken: credential.refreshToken,
+			expiresAt: credential.expiresAt,
+			refreshed: false,
+		};
+	}
+	const existing = inFlight.get(credential.refreshToken);
+	if (existing) return { ...(await existing), refreshed: true };
+	const task = refreshClineToken(credential.refreshToken).finally(() => {
+		inFlight.delete(credential.refreshToken);
+	});
+	inFlight.set(credential.refreshToken, task);
+	const update = await task;
+	return { ...update, accessToken: formatClineAccessToken(update.accessToken), refreshed: true };
+}
+// ── Device flow (initial sign-in) ───────────────────────────────────────────
+
+interface WorkOSDeviceAuthorizationResponse {
+	device_code?: string;
+	user_code?: string;
+	verification_uri?: string;
+	verification_uri_complete?: string;
+	expires_in?: number;
+	interval?: number;
+	error?: string;
+	error_description?: string;
+}
+
+interface WorkOSTokenResponse {
+	access_token?: string;
+	refresh_token?: string;
+	token_type?: string;
+	error?: string;
+	error_description?: string;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Interactive sign-in: request a device code, hand the verification URL to
+ * `onAuthInfo`, and start polling immediately — `onAuthInfo` must NOT block
+ * until dismissal (the old code awaited a modal dialog here, so polling only
+ * began after the user pressed enter and a completed browser approval sat
+ * unnoticed). Call `onAuthorized` (via the options below) once the first poll
+ * succeeds so the UI can auto-close the panel; the panel's dismissal promise
+ * is awaited before returning so the two UI layers never interleave.
+ */
+export async function loginClineDeviceFlow(options: {
+	/** Show the verification URL/user code; resolve without waiting for dismissal. */
+	onAuthInfo: (info: { url: string; userCode: string }) => Promise<void>;
+	/** Called when the browser approval is confirmed — the UI can auto-close its auth panel. */
+	onAuthorized?: () => void;
+	/** Optional progress lines while polling (e.g. append to a progress panel). */
+	onProgress?: (message: string) => void;
+}): Promise<ClineTokenUpdate> {
+	// One retry: a transient network blip here aborts the whole sign-in before
+	// the user even sees a URL (observed: "fetch failed" after ~12s once).
+	let authResponse: Response | undefined;
+	let lastFetchError: unknown;
+	for (let attempt = 1; attempt <= 2 && !authResponse; attempt++) {
+		try {
+			authResponse = await fetch(`${WORKOS_API_BASE_URL}${WORKOS_DEVICE_AUTHORIZATION_PATH}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams({ client_id: WORKOS_CLIENT_ID }),
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+			});
+		} catch (error) {
+			lastFetchError = error;
+			if (attempt < 2) await sleep(1500);
+		}
+	}
+	if (!authResponse) {
+		const detail = lastFetchError instanceof Error ? `${lastFetchError.message}${lastFetchError.cause instanceof Error ? ` (${lastFetchError.cause.message})` : ""}` : String(lastFetchError);
+		throw new Error(`Cline device authorization failed: could not reach api.workos.com (${detail})`);
+	}
+	const device = (await authResponse.json().catch(() => ({}))) as WorkOSDeviceAuthorizationResponse;
+	if (!authResponse.ok || !device.device_code || !device.user_code || !device.verification_uri) {
+		const detail = device.error_description ?? (authResponse.ok ? "invalid WorkOS response" : `HTTP ${authResponse.status}`);
+		throw new Error(`Cline device authorization failed: ${detail}`);
+	}
+
+	// Hand the URL to the UI but do NOT wait for the panel to be dismissed —
+	// polling must start now, or an already-completed browser approval goes
+	// unnoticed until the user dismisses the panel manually.
+	const panelDismissed = options.onAuthInfo({
+		url: device.verification_uri_complete ?? device.verification_uri,
+		userCode: device.user_code,
+	}).catch(() => {});
+
+	const expiresInSeconds = device.expires_in ?? DEVICE_AUTH_EXPIRES_IN_SECONDS;
+	const deadline = Date.now() + expiresInSeconds * 1000;
+	let intervalSeconds = Math.max(1, device.interval ?? DEVICE_AUTH_INTERVAL_SECONDS);
+	let workosTokens: { access: string; refresh: string } | undefined;
+	let pollCount = 0;
+
+	while (Date.now() <= deadline) {
+		pollCount++;
+		const pollResponse = await fetch(`${WORKOS_API_BASE_URL}${WORKOS_AUTHENTICATE_PATH}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+				device_code: device.device_code,
+				client_id: WORKOS_CLIENT_ID,
+			}),
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+		});
+		const payload = (await pollResponse.json().catch(() => ({}))) as WorkOSTokenResponse;
+		if (pollResponse.ok) {
+			if (!payload.access_token || !payload.refresh_token) {
+				throw new Error("Invalid WorkOS token response");
+			}
+			workosTokens = { access: payload.access_token, refresh: payload.refresh_token };
+			options.onAuthorized?.();
+			await panelDismissed;
+			break;
+		}
+		switch (payload.error) {
+			case "authorization_pending":
+				options.onProgress?.("Waiting for browser authentication confirmation…");
+				await sleep(intervalSeconds * 1000);
+				break;
+			case "slow_down":
+				intervalSeconds += 1;
+				await sleep(intervalSeconds * 1000);
+				break;
+			case "access_denied":
+				throw new Error(`Cline authorization failed: ${payload.error_description ?? payload.error}`);
+			case "expired_token":
+				throw new Error(`Cline authorization timed out: ${payload.error_description ?? payload.error}`);
+			case "invalid_grant":
+				throw new Error(`Cline authorization failed: ${payload.error_description ?? payload.error}`);
+			default:
+				throw new Error(`WorkOS token polling failed: HTTP ${pollResponse.status}${payload.error_description ? ` — ${payload.error_description}` : ""}`);
+		}
+	}
+	if (!workosTokens) throw new Error("WorkOS device authorization timed out");
+
+	// Exchange the WorkOS tokens for Cline account tokens.
+	const registerResponse = await fetch(`${CLINE_API_BASE_URL}${CLINE_REGISTER_PATH}`, {
+		method: "POST",
+		headers: clineAuthHeaders(),
+		body: JSON.stringify({ accessToken: workosTokens.access, refreshToken: workosTokens.refresh }),
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+	});
+	if (!registerResponse.ok) {
+		const text = await registerResponse.text().catch(() => "");
+		throw new Error(`Cline token registration failed: HTTP ${registerResponse.status}${text ? ` — ${text.slice(0, 200)}` : ""}`);
+	}
+	const payload = (await registerResponse.json().catch(() => ({}))) as ClineTokenResponse;
+	return requireClineTokens(payload, "Invalid Cline token registration response");
+}
+
+/** Human-readable expiry line for the TUI (token state only; quota lives server-side). */
+export function describeClineCredential(credential: KeyCredential): string {
+	if (credential.expiresAt === undefined) return "token expiry unknown";
+	const remaining = credential.expiresAt - Date.now();
+	if (remaining <= 0) return `token expired ${Math.round(-remaining / 60_000)}m ago`;
+	if (remaining < 90_000) return `token expires in ${Math.round(remaining / 1000)}s`;
+	if (remaining < 90 * 60_000) return `token expires in ${Math.round(remaining / 60_000)}m`;
+	return `token expires in ${Math.round(remaining / 3_600_000)}h`;
+}
+

package/config.ts

@@ -11,6 +11,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import type { AuthStyle } from "./probe.ts";
+import { currentRequestId, currentSessionId, currentTaskId, turnKeyOf } from "./identity.ts";
 
 /** Safe model defaults applied when a spec doesn't say otherwise (edit in multikey.json). */
 export const DEFAULT_CONTEXT_WINDOW = 128_000;
@@ -37,6 +38,36 @@ export interface PoolKeyConfig {
 	label?: string;
 	/** Disabled keys are never selected. Default: true. */
 	enabled?: boolean;
+	/**
+	 * Credential-backed key (Cline account OAuth). When present, `key` holds the
+	 * current access token and is refreshed transparently from `credential`
+	 * before requests and again on 401 — see cline-auth.ts.
+	 */
+	credential?: KeyCredential;
+}
+
+/** OAuth-style credential for endpoints without static API keys (Cline free tier). */
+export interface KeyCredential {
+	kind: "cline-oauth";
+	/** Long-lived refresh token; access tokens are minted from it. */
+	refreshToken: string;
+	/** Last known access token (mirrors `key`). */
+	accessToken?: string;
+	/** Access token expiry (epoch ms), when known. */
+	expiresAt?: number;
+}
+
+/**
+ * Tracks which shipped preset a pool was created from / last aligned with.
+ * Lives in multikey.json as `_preset`. The fingerprint (see presetFingerprint
+ * in presets.ts) is persisted the moment an update prompt is shown — that is
+ * what guarantees each preset version is asked about at most once.
+ */
+export interface PresetMarker {
+	/** Preset id in presets.ts, e.g. "b-ai". */
+	id: string;
+	/** Fingerprint of the preset's model list at pool creation / last sync. */
+	fingerprint: string;
 }
 
 export interface PoolModelConfig {
@@ -70,6 +101,8 @@ export interface PoolConfig {
 	cooldownMs?: number;
 	/** Cooldown after a 401/403 (bad key). Default 600000ms. */
 	invalidKeyCooldownMs?: number;
+	/** Present when the pool was created from (or adopted) a shipped preset. */
+	_preset?: PresetMarker;
 	keys: PoolKeyConfig[];
 	models: PoolModelConfig[];
 }
@@ -260,7 +293,8 @@ export function loadConfig(): { config: KeypoolConfig; created: boolean; migrate
 		return { config, created: true };
 	}
 	const raw = JSON.parse(readFileSync(path, "utf-8")) as KeypoolConfig;
-	return { config: normalize(raw), created: false };
+	const config = normalize(raw);
+	return { config, created: false };
 }
 
 export function saveConfig(config: KeypoolConfig): void {
@@ -280,6 +314,17 @@ export function normalize(config: KeypoolConfig): KeypoolConfig {
 	return { pools: normalized };
 }
 
+/** Structural check so a malformed credential in the JSON file can't break a pool. */
+function isValidCredential(credential: unknown): credential is KeyCredential {
+	return (
+		!!credential &&
+		typeof credential === "object" &&
+		(credential as KeyCredential).kind === "cline-oauth" &&
+		typeof (credential as KeyCredential).refreshToken === "string" &&
+		(credential as KeyCredential).refreshToken.trim().length > 0
+	);
+}
+
 function normalizePool(pool: PoolConfig): PoolConfig {
 	const keys = (Array.isArray(pool.keys) ? pool.keys : [])
 		.filter((k) => k && typeof k.key === "string" && k.key.trim())
@@ -287,8 +332,14 @@ function normalizePool(pool: PoolConfig): PoolConfig {
 			key: k.key.trim(),
 			label: typeof k.label === "string" && k.label.trim() ? k.label.trim() : undefined,
 			enabled: k.enabled !== false,
+			// OAuth-backed keys keep their credential; only well-formed ones survive.
+			...(isValidCredential(k.credential) ? { credential: k.credential } : {}),
 		}));
 	const models = (Array.isArray(pool.models) ? pool.models : []).filter((m) => m && typeof m.id === "string" && m.id.trim());
+	const preset =
+		pool._preset && typeof pool._preset.id === "string" && typeof pool._preset.fingerprint === "string"
+			? { id: pool._preset.id, fingerprint: pool._preset.fingerprint }
+			: undefined;
 	return {
 		id: pool.id.trim(),
 		name: pool.name ?? pool.id,
@@ -302,6 +353,7 @@ function normalizePool(pool: PoolConfig): PoolConfig {
 			typeof pool.invalidKeyCooldownMs === "number" && pool.invalidKeyCooldownMs >= 0
 				? pool.invalidKeyCooldownMs
 				: DEFAULT_INVALID_KEY_COOLDOWN_MS,
+		_preset: preset,
 		keys,
 		models,
 	};
@@ -342,21 +394,78 @@ export function maskKey(key: string): string {
 
 // ── Endpoint-required headers ────────────────────────────────────────────────
 
-/** OpenCode Zen free tier endpoint that requires a specific User-Agent header. */
+/** OpenCode Zen free tier endpoint that mimics the official OpenCode client. */
 const OPENCODE_ZEN_BASE_URL = "https://opencode.ai/zen/v1";
-const OPENCODE_ZEN_USER_AGENT =
-	"opencode/1.15.0 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.13";
+const OPENCODE_ZEN_USER_AGENT = "opencode/0.1.50 ai-sdk/openai-compatible/3.0.41";
+const OPENCODE_ZEN_CLIENT = "tui";
+
+/** True when a baseUrl points at OpenCode Zen (case-insensitive, trailing slash ok). */
+export function isOpenCodeZenEndpoint(baseUrl: string | undefined): boolean {
+	if (!baseUrl) return false;
+	return baseUrl.replace(/\/+$/, "").toLowerCase() === OPENCODE_ZEN_BASE_URL;
+}
 
 /**
- * Headers that must be sent to known endpoints.
- *
- * Currently: OpenCode Zen's free tier endpoint requires this exact User-Agent;
- * anything else returns an empty object.
+ * Constant headers a known endpoint expects on every request.
  *
- * The comparison is case-insensitive and tolerates a trailing slash.
+ * OpenCode Zen's free tier wants the full OpenCode client header set; the
+ * per-conversation / per-device halves live in {@link endpointIdentityHeaders}.
+ * Cline's API gates on its official client's header set (versioned client
+ * identity + platform metadata), so we send the same shape the Cline CLI
+ * sends (mirroring sdk request-headers.ts). Anything else returns an empty object.
  */
 export function endpointHeaders(baseUrl: string): Record<string, string> {
-	const normalized = baseUrl.replace(/\/+$/, "").toLowerCase();
-	if (normalized === OPENCODE_ZEN_BASE_URL) return { "User-Agent": OPENCODE_ZEN_USER_AGENT };
-	return {};
+	if (isClineEndpoint(baseUrl)) return clineClientHeaders();
+	if (!isOpenCodeZenEndpoint(baseUrl)) return {};
+	return { "x-opencode-client": OPENCODE_ZEN_CLIENT, "User-Agent": OPENCODE_ZEN_USER_AGENT };
+}
+
+/**
+ * Per-request identity headers a known endpoint expects.
+ *
+ * OpenCode Zen reads `x-opencode-session` as the conversation id and
+ * `x-opencode-request` as the id of the user message being answered, so these
+ * must be computed at request time rather than baked into the provider
+ * registration. `messages` lets the caller key the request id to the current
+ * turn (see turnKeyOf); omit it for one-shot calls outside a conversation.
+ * Cline reads `X-Task-ID` as a per-conversation correlation id.
+ */
+export function endpointIdentityHeaders(baseUrl: string | undefined, messages?: readonly unknown[]): Record<string, string> {
+	if (isClineEndpoint(baseUrl ?? "")) return { "X-Task-ID": currentTaskId() };
+	if (!isOpenCodeZenEndpoint(baseUrl ?? "")) return {};
+	return {
+		"x-opencode-session": currentSessionId(),
+		"x-opencode-request": currentRequestId(messages ? turnKeyOf(messages) : undefined),
+	};
+}
+
+// ── Cline (api.cline.bot) ────────────────────────────────────────────────────
+
+const CLINE_API_BASE_URL = "https://api.cline.bot";
+
+/**
+ * Header set the official Cline CLI sends to api.cline.bot (mirrors
+ * cline sdk request-headers.ts buildClineRequestHeaders with source "cli").
+ * The values track the cline repo versions: CLI 3.0.61, SDK core 0.0.82.
+ */
+const CLINE_CLIENT_HEADERS: Record<string, string> = {
+	"HTTP-Referer": "https://cline.bot",
+	"X-Title": "Cline",
+	"X-IS-MULTIROOT": "false",
+	"X-CLIENT-TYPE": "cline-cli",
+	"User-Agent": "Cline/3.0.61",
+	"X-CLIENT-VERSION": "3.0.61",
+	"X-PLATFORM": "cli",
+	"X-PLATFORM-VERSION": "3.0.61",
+	"X-CORE-VERSION": "0.0.82",
+};
+
+function clineClientHeaders(): Record<string, string> {
+	return { ...CLINE_CLIENT_HEADERS };
+}
+
+/** True when a baseUrl points at Cline's API (any path depth, trailing slash ok). */
+export function isClineEndpoint(baseUrl: string | undefined): boolean {
+	if (!baseUrl) return false;
+	return baseUrl.replace(/\/+$/, "").toLowerCase().startsWith(CLINE_API_BASE_URL);
 }