opencode-auth-load-balancer 0.4.0 → 0.5.0

package/dist/providers/anthropic/constants.d.ts

@@ -83,6 +83,33 @@ export declare const FALLBACK_CLAUDE_CODE_VERSION = "2.1.258";
  * `cch` fingerprint algorithm and the newest version starts 400ing).
  */
 export declare const CLAUDE_CODE_VERSION_ENV = "OPENCODE_AUTH_LB_ANTHROPIC_CLAUDE_CODE_VERSION";
+/**
+ * The structured error code Anthropic answers a version-gated model with:
+ *
+ * ```json
+ * {"type":"error","error":{"type":"invalid_request_error",
+ *  "message":"Claude Code 2.1.278 does not support this model; version 2.1.280 or newer is required.",
+ *  "details":{"error_code":"claude_code_version_too_old"}}}
+ * ```
+ *
+ * Matched as a SUBSTRING of the raw body rather than through a parsed path
+ * (`error.details.error_code`): the envelope's shape is Anthropic's to change,
+ * and this string appearing anywhere in a rejection is both sufficient — no
+ * other error carries it — and immune to a reshuffle that would silently break
+ * a path lookup. See `recoverClaudeCodeVersion` in version.ts.
+ */
+export declare const CLAUDE_CODE_VERSION_GATE_CODE = "claude_code_version_too_old";
+/**
+ * The MINIMUM version that rejection's human-readable message demands.
+ *
+ * Anchored on the `or newer is required` tail rather than the first version in
+ * the string, because the message names TWO: the one we just sent ("Claude
+ * Code 2.1.278 does not support this model") and the one being asked for
+ * ("version 2.1.280 or newer is required"). Capturing the leading one would
+ * adopt the version that just failed — a no-op the recovery would correctly
+ * refuse to retry, i.e. a silent regression to the old stuck behavior.
+ */
+export declare const CLAUDE_CODE_REQUIRED_VERSION_RE: RegExp;
 /**
  * npm dist-tags for the Claude Code CLI — `{"latest":"2.1.258",…}`, ~56 bytes.
  * Deliberately NOT `/@anthropic-ai/claude-code/latest`, which returns the whole

package/dist/providers/anthropic/version.d.ts

@@ -20,6 +20,27 @@ export declare function usageUserAgent(): string;
  * usable answer, so a failure does NOT refresh the TTL).
  */
 export declare function refreshClaudeCodeVersion(now: number): Promise<void>;
+/**
+ * REACTIVE recovery, driven by the gate's own rejection.
+ *
+ * `primeClaudeCodeVersion` resolves once at startup and then trusts the cache
+ * for `CLAUDE_CODE_VERSION_TTL_MS`. A model that launches INSIDE that window is
+ * therefore rejected for as long as the TTL has left to run — up to a full day
+ * of hard failures — even when npm already tags the version Anthropic is asking
+ * for, and even though the rejection itself NAMES that version. No polling
+ * cadence fixes this in general either: Anthropic can gate a model before npm
+ * tags the release, which is why the env pin exists as a manual escape hatch.
+ *
+ * So learn from the rejection instead. Adopt the minimum it demands, then ask
+ * npm for the real `latest` in the same breath — the minimum only clears the
+ * model that just failed, whereas `latest` is what the NEXT launch will want.
+ *
+ * Returns whether the reported version actually MOVED, which is precisely the
+ * condition under which a retry can succeed; the caller spends a second
+ * round-trip on true and passes the rejection through untouched on false.
+ * `res` is consumed, so callers that still need the body must pass a clone.
+ */
+export declare function recoverClaudeCodeVersion(res: Response, now: number): Promise<boolean>;
 /**
  * Startup hook. Awaits only the LOCAL cache read — cheap, and enough to have
  * the right version in hand before the loader returns the fetch — then leaves

package/dist/providers/kimi/adapter.d.ts

@@ -0,0 +1,13 @@
+import { type ProviderAdapter } from '../types';
+import { type KimiDeployment } from './constants';
+/**
+ * Kimi Code adapter for one deployment. A subscription joins the pool either
+ * through a device-code OAuth login (`startDeviceLogin`, refreshed by
+ * `refresh`) or as a pasted API key (`authorize`/`exchange` +
+ * `tokensFromApiKey`). opencode already shapes the requests as
+ * OpenAI-compatible chat completions, so they pass through untouched, and
+ * inference responses carry no quota headers: usage comes from `/usages`.
+ */
+export declare function createKimiAdapter(deployment: KimiDeployment): ProviderAdapter;
+export declare const kimiCodeAdapter: ProviderAdapter;
+export declare const kimiCodeGlobalAdapter: ProviderAdapter;

package/dist/providers/kimi/constants.d.ts

@@ -0,0 +1,36 @@
+export { OAUTH_HTTP_TIMEOUT_MS, USAGE_HTTP_TIMEOUT_MS } from '../http-timeouts';
+/**
+ * One Kimi Code deployment. kimi.com and kimi.ai are separate hosts with
+ * separate accounts, and opencode's models.dev catalog lists each as its own
+ * provider — so each gets its own adapter, and its own pool.
+ */
+export interface KimiDeployment {
+    /** opencode provider id (models.dev). */
+    readonly id: string;
+    /** OpenAI-compatible API base (the catalog's `api`); `/usages` and `/me` live here too. */
+    readonly baseUrl: string;
+    /** OAuth host for the device-code login and token refresh. */
+    readonly oauthHost: string;
+    /** Console page where a subscriber creates the API key the key login asks for. */
+    readonly consoleUrl: string;
+}
+export declare const KIMI_CODE: KimiDeployment;
+export declare const KIMI_CODE_GLOBAL: KimiDeployment;
+/** Kimi Code's public OAuth client, shared by both deployments (no secret). */
+export declare const KIMI_OAUTH_CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098";
+/**
+ * `X-Msh-Platform` / `X-Msh-Version` sent to the OAuth host. Kimi's SDK asks
+ * every host to name itself rather than borrow its CLI's `kimi_code_cli`, so
+ * this names the plugin; the version is this integration's, bumped when its
+ * handling of the login protocol changes.
+ */
+export declare const KIMI_DEVICE_PLATFORM = "opencode_auth_load_balancer";
+export declare const KIMI_DEVICE_VERSION = "1";
+/** Local wall-clock budget for one device-code login (Kimi's own clients use 15 min). */
+export declare const DEVICE_LOGIN_TIMEOUT_MS: number;
+/**
+ * `expires` stamped on a static-key row: a key does not expire client-side,
+ * so `needsRefresh` must never fire. Finite, so the pool store's
+ * `Number.isFinite(expires)` normalization keeps it.
+ */
+export declare const STATIC_KEY_EXPIRES: number;

package/dist/providers/kimi/key.d.ts

@@ -0,0 +1,18 @@
+import type { TokenSet } from '../../types';
+import { type KimiDeployment } from './constants';
+/**
+ * Map a Kimi Code API key onto the pool's token shape: the key is the bearer,
+ * with no refresh token and an expiry that never comes due. `accountId` is a
+ * fingerprint of the key — `addAccount` dedups on it — which a login upgrades
+ * to the Kimi account id; this bare form serves the startup import, where no
+ * network call can run.
+ */
+export declare function tokensFromApiKey(key: string): TokenSet;
+/**
+ * The pasted key, checked against `GET /me` before it can join the pool: a
+ * typo, a Moonshot open-platform key, or a stray URL fails the login instead
+ * of adding a row that only ever 401s. The row is keyed by the Kimi account
+ * behind the key, so a second key — or an OAuth login — for the same
+ * subscription replaces its row instead of double-counting one quota.
+ */
+export declare function exchange(deployment: KimiDeployment, input: string): Promise<TokenSet | null>;

package/dist/providers/kimi/oauth.d.ts

@@ -0,0 +1,22 @@
+import type { TokenSet } from '../../types';
+import type { DeviceLogin } from '../types';
+import { type KimiDeployment } from './constants';
+/** The poll loop's clock — a seam so tests need not wait out real intervals. */
+export interface PollClock {
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Start a device-code login: the URL (user code embedded) to approve in a
+ * browser, and `complete` — the wait for that approval. The approved login is
+ * keyed by the Kimi account behind it (`GET /me`), like a key login, so one
+ * subscription stays one pool row however it signs in.
+ */
+export declare function startDeviceLogin(deployment: KimiDeployment, clock?: PollClock): Promise<DeviceLogin>;
+/**
+ * Refresh a Kimi Code OAuth row. Kimi answers a revoked grant with 400
+ * `invalid_grant`, 401 or 403, and each means re-login: 400/401 already carry
+ * the status refresh.ts parks rows on, so only 403 is spelled out as
+ * `invalid_grant`. A key row has no refresh token to spend at all.
+ */
+export declare function refreshOAuth(deployment: KimiDeployment, refreshToken: string): Promise<TokenSet>;

package/dist/providers/kimi/profile.d.ts

@@ -0,0 +1,10 @@
+/** What `GET /me` says about the account behind a bearer. */
+export interface KimiProfile {
+    /** Kimi's account id: one per subscription, whichever key or login reaches it. */
+    readonly userId?: string;
+}
+/**
+ * `GET {baseUrl}/me` with an API key or an OAuth access token. Null when the
+ * bearer is refused or the call fails, so it doubles as the key check.
+ */
+export declare function fetchProfile(baseUrl: string, bearer: string): Promise<KimiProfile | null>;

package/dist/providers/kimi/usage.d.ts

@@ -0,0 +1,12 @@
+import type { PoolAccount, UsageSnapshot } from '../../types';
+/**
+ * Parse `GET /usages` into the pool's snapshot, one window at a time: the
+ * ratio shape (`usages.limit_5h` / `limit_7d`) first, the counter shape as
+ * that window's fallback. Null when neither window parses, so a foreign or
+ * broken body keeps the last-known snapshot instead of reading as 0% used.
+ */
+export declare function parseUsages(json: unknown, now: number): UsageSnapshot | null;
+/** `GET {baseUrl}/usages` — free, spends no quota. Null on any failure. */
+export declare function getUsages(baseUrl: string, key: string): Promise<unknown>;
+/** The adapter's `fetchUsage` for one deployment. */
+export declare function usageFetcher(baseUrl: string): (account: PoolAccount, now: number) => Promise<UsageSnapshot | null>;

package/dist/providers/oauth-callback.d.ts

@@ -98,3 +98,17 @@ export declare function parseCallbackInput(input: string, options?: {
     code: string;
     state: string;
 } | null;
+/**
+ * `parseCallbackInput`, plus the authorization code on its own — what a user
+ * naturally copies out of the callback's `?code=…` when the login prompt asks
+ * for "the authorization code". A bare code carries no `state`, so it comes
+ * back as `state: null` and the caller skips its CSRF comparison for it. PKCE
+ * keeps that safe: a code only redeems together with the `code_verifier`
+ * generated for THIS login attempt, so a code minted for any other attempt is
+ * useless here. A pasted callback still returns its `state` for the caller to
+ * enforce.
+ */
+export declare function parseCodeInput(input: string): {
+    code: string;
+    state: string | null;
+} | null;

package/dist/providers/openai/oauth.d.ts

@@ -3,9 +3,12 @@ import type { AuthorizeRequest } from '../types';
 /** Begin the ChatGPT PKCE authorization flow. */
 export declare function authorize(): Promise<AuthorizeRequest>;
 /**
- * Exchange a pasted callback URL (or `code#state`) for tokens. Returns null on
- * failure. The redirect lands on http://localhost:1455/auth/callback — the user
- * copies that URL from the browser address bar and pastes it here.
+ * Exchange the pasted login result for tokens. Returns null on failure. The
+ * redirect lands on http://localhost:1455/auth/callback, a page that never
+ * loads — so the user pastes either that whole URL from the address bar (or
+ * its `code=…&state=…` query) or just the authorization code itself, which is
+ * what the login prompt asks for. A pasted `state` must match this attempt's;
+ * a bare code has none to compare (see `parseCodeInput`).
  */
 export declare function exchange(input: string, verifier: string, redirectUri: string, expectedState?: string): Promise<TokenSet | null>;
 /** Refresh an access token. Throws on failure; message includes the HTTP status. */

package/dist/providers/types.d.ts

@@ -28,6 +28,17 @@ export interface AuthorizeRequest {
     verifier: string;
     state: string;
     redirectUri: string;
+    /** Login prompt text; absent = the OAuth default ("Paste the authorization code here:"). */
+    instructions?: string;
+}
+/** A device-code login (RFC 8628) in flight: where to approve it, and the wait for approval. */
+export interface DeviceLogin {
+    /** Verification URL to open (the user code rides in it). */
+    url: string;
+    /** Prompt shown with the URL, e.g. the user code to confirm. */
+    instructions: string;
+    /** Resolve with the approved tokens, or null when denied, expired, or failed. */
+    complete(): Promise<TokenSet | null>;
 }
 /**
  * A request-body rewrite that downgrades the requested model to a cheaper
@@ -79,6 +90,24 @@ export interface ProviderAdapter {
     exchange(input: string, verifier: string, redirectUri: string, state: string): Promise<TokenSet | null>;
     /** Refresh an access token. Throws on failure (callers handle invalid_grant). */
     refresh(refreshToken: string): Promise<TokenSet>;
+    /**
+     * Start a device-code login, for providers whose OAuth has no redirect to
+     * paste back (Kimi Code). Registered as an `auto` login method ahead of the
+     * paste flow; absent on Claude/Codex.
+     */
+    startDeviceLogin?(): Promise<DeviceLogin>;
+    /**
+     * Present on providers that also take a static API key (Kimi Code): maps a
+     * key onto the pool's TokenSet. A key has no refresh token behind it, so
+     * its presence switches three credential paths:
+     *  - the paste login (`authorize`/`exchange`) collects a key, and its
+     *    callback hands opencode `{ key }`, stored as a plain `api` credential;
+     *  - the auth loader also imports opencode's `api` credential, which
+     *    OAuth-only providers ignore;
+     *  - a 401 parks a key row (one without a refresh token) for a re-login
+     *    instead of cooling it down — no refresh can repair a revoked key.
+     */
+    tokensFromApiKey?(key: string): TokenSet;
     /** Set auth + provider headers on an outgoing request for the chosen account. */
     applyAuth(headers: Headers, account: PoolAccount): void;
     /** Optionally rewrite the request URL (e.g. add ?beta=true, swap base URL). */
@@ -136,4 +165,24 @@ export interface ProviderAdapter {
      * downgraded body. null = treat the 429 as a normal account rotation.
      */
     planReactiveFallback?(res: Response, body: string, now: number, models: readonly string[]): ReactiveModelFallback | null;
+    /**
+     * REACTIVE recovery from a CLIENT-VERSION gate: a provider may reject an
+     * otherwise-valid request until the plugin claims to be a newer client
+     * (Anthropic answers a too-new model with 400 `claude_code_version_too_old`,
+     * naming the minimum it wants). Such a status classifies as `ok` — the fetch
+     * loop is one statement away from handing it to the caller — so this is the
+     * last point at which it can become a recoverable event instead of a failed
+     * turn.
+     *
+     * Return true ONLY when the version the adapter will now report actually
+     * changed: the fetch loop reads that as "a retry can succeed" and restarts
+     * the request once. Returning true without a change would buy a second,
+     * byte-identical round-trip and the same rejection.
+     *
+     * `res` is a CLONE the implementation may consume freely; the original is
+     * still returned to the caller when this resolves false. Absent on providers
+     * with no such gate (OpenAI) — the fetch loop treats that as "nothing to
+     * recover".
+     */
+    recoverClientVersion?(res: Response, now: number): Promise<boolean>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-auth-load-balancer",
-  "version": "0.4.0",
-  "description": "Load-balance opencode requests across multiple Anthropic (Claude) and OpenAI (Codex) OAuth accounts, weighted primarily by weekly usage with drain-before-reset scheduling.",
+  "version": "0.5.0",
+  "description": "Load-balance opencode requests across multiple Anthropic (Claude) and OpenAI (Codex) OAuth accounts and Kimi Code subscriptions, weighted primarily by weekly usage with drain-before-reset scheduling.",
   "type": "module",
   "license": "MIT",
   "author": "owjs3901",
@@ -62,6 +62,8 @@
     "claude",
     "openai",
     "codex",
+    "kimi",
+    "kimi-code",
     "oauth",
     "load-balancer"
   ],

package/tui/auth-load-balancer-tui.logic.ts

@@ -62,6 +62,8 @@ export interface PoolAccount {
   /** LEGACY pre-tier-map field (folded into `modelCooldownsUntil.opus` for display until the server migrates the file). */
   opusCooldownUntil?: number
   disabledReason?: string | null
+  /** Empty on a static API-key row (Kimi Code), which re-logs in with a new key. */
+  refresh?: string
 }
 /** Loosely-typed view of the on-disk pool JSON (one shape for reads AND read-modify-writes). */
 export interface PoolShape {
@@ -276,16 +278,24 @@ export function clearReloginTargetInPool(path: string = POOL_FILE): void {
  * opencode aggregates auth methods from every plugin registered for a provider,
  * so this plugin's position is not stable. Prefer its pooled-login label, then
  * fall back to the provider's first OAuth method when no such label is present.
+ * A provider can offer both an account login and an API-key login (Kimi
+ * Code), so `apiKey` picks the kind that matches how the row was added.
  */
 export function pickAuthMethodIndex(
   methods: readonly { type?: string; label?: string }[] | undefined,
+  apiKey = false,
 ): number | null {
-  const pooled = methods?.findIndex(
+  const pooled = (method: { type?: string; label?: string }): boolean =>
+    method.type === 'oauth' &&
+    (method.label?.toLowerCase().includes('load balancer') ?? false)
+  const sameKind = methods?.findIndex(
     (method) =>
-      method.type === 'oauth' &&
-      method.label?.toLowerCase().includes('load balancer'),
+      pooled(method) &&
+      (method.label?.toLowerCase().includes('api key') ?? false) === apiKey,
   )
-  if (pooled !== undefined && pooled >= 0) return pooled
+  if (sameKind !== undefined && sameKind >= 0) return sameKind
+  const anyPooled = methods?.findIndex(pooled)
+  if (anyPooled !== undefined && anyPooled >= 0) return anyPooled
   const oauth = methods?.findIndex((method) => method.type === 'oauth')
   return oauth !== undefined && oauth >= 0 ? oauth : null
 }

package/tui/auth-load-balancer-tui.view.tsx

@@ -57,6 +57,8 @@ import {
 const PROVIDER_NAMES: Record<string, string> = {
   anthropic: 'Claude',
   openai: 'Codex',
+  'kimi-code-plan-cn': 'Kimi',
+  'kimi-code-plan-global': 'Kimi (kimi.ai)',
 }
 /** Shared fallback lookup used by both the bottom bar and sidebar group labels. */
 function providerLabel(id: string): string {
@@ -200,6 +202,8 @@ interface Row extends WindowDisplay {
   rank: number | null
   state: string
   manuallyDisabled: boolean
+  /** A static API-key row: re-login asks for a new key, not an OAuth sign-in. */
+  apiKey: boolean
 }
 interface Group {
   provider: string
@@ -264,6 +268,7 @@ function SidebarPanel(props: {
           // tier annotation forever until the server heals the file.
           state: stateOf(sa, tierResets(a, now), now),
           manuallyDisabled: a.disabledReason === MANUAL_DISABLED_REASON,
+          apiKey: a.refresh === '',
         }
       })
       return { provider: providerLabel(providerID), rows }
@@ -306,12 +311,13 @@ function SidebarPanel(props: {
     id: string,
     label: string,
     providerID: string,
+    apiKey: boolean,
   ): Promise<void> {
     try {
       const methods = (await props.api.client.provider.auth()).data?.[
         providerID
       ]
-      const method = pickAuthMethodIndex(methods)
+      const method = pickAuthMethodIndex(methods, apiKey)
       if (method === null) {
         props.api.ui.toast({
           variant: 'error',
@@ -372,6 +378,15 @@ function SidebarPanel(props: {
       }
 
       if (auth.method === 'auto') {
+        // A device-code login (Kimi Code) completes in the browser: show where
+        // to approve it for as long as the callback waits.
+        dialog().replace(() =>
+          props.api.ui.DialogAlert({
+            title: `Re-login "${label}"`,
+            message: `${auth.instructions}\n\n${auth.url}`,
+            onConfirm: () => dialog().clear(),
+          }),
+        )
         await completeRelogin()
         return
       }
@@ -423,6 +438,7 @@ function SidebarPanel(props: {
     label: string,
     providerID: string,
     manuallyDisabled: boolean,
+    apiKey: boolean,
   ): void {
     const items: { title: string; run: () => void }[] = [
       { title: 'Rename', run: () => openRename(id, label) },
@@ -440,7 +456,7 @@ function SidebarPanel(props: {
       {
         title: 'Re-login — re-authorize with the provider',
         run: () => {
-          void openRelogin(id, label, providerID)
+          void openRelogin(id, label, providerID, apiKey)
         },
       },
       { title: 'Delete — remove from pool', run: () => openDelete(id, label) },
@@ -503,7 +519,13 @@ function SidebarPanel(props: {
                 {(r) => (
                   <box
                     onMouseUp={() =>
-                      openMenu(r.id, r.label, r.providerID, r.manuallyDisabled)
+                      openMenu(
+                        r.id,
+                        r.label,
+                        r.providerID,
+                        r.manuallyDisabled,
+                        r.apiKey,
+                      )
                     }
                   >
                     <text