pi-freeflow 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.22.0
+
+### Minor Changes
+
+- Sign in to Cline right inside the extension: `/freeflow cline login` shows a browser link and code, approves your own Cline account, and saves it to a per-user pool on your machine — no pasting keys. Extra logins auto-name themselves (`default`, `slot-2`, …), saved logins refresh on their own, and requests roll across them when one hits its daily free limit. Pasting a key stays available behind `login --key`. Model selection labels every free model with its source ([OpenCode], [Kilo], [Cline]).
+
 ## 1.21.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # pi-freeflow
 
-> 27 free models with up to 1M context. No API keys to manage. Add your own relays to spread requests across more IPs.
+> 31 free models with up to 1M context. No API keys to manage. Add your own relays to spread requests across more IPs.
 
 Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handles thinking, normalization, and provider behavior.
 
@@ -16,7 +16,7 @@ Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handl
 
 | Feature | What it does | Cost |
 | :--- | :--- | :--- |
-| **27 free models** | 8 from OpenCode Zen, 19 from KiloCode Gateway, context windows up to 1M. Full list below. | **$0** |
+| **31 free models** | 8 from OpenCode Zen, 19 from KiloCode Gateway, 4 from Cline, context windows up to 1M. Full list below. | **$0** |
 | **Relay pool** | Route requests through your own Cloudflare Workers and Vercel Edge relays. Requests rotate across the pool. A relay that rate-limits, times out, or drops the connection cools down while healthy ones take its traffic. | **$0** beyond your platforms' free tiers |
 | **Automatic fallback** | When every relay is cooling down, requests go direct to upstream instead of failing. | **$0** |
 | **Short model names** | Every model has a slash-free, colon-free alias, plus an optional `:effort` suffix for thinking depth. You type `freeflow/<name>`. | **$0** |
@@ -174,13 +174,16 @@ The same command set works identically in OMP and Pi:
 /freeflow update                  # Check for and install a package update
 /freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
 /freeflow kill                    # Stop the shared proxy daemon now (restarts on next use)
+/freeflow cline login               # Sign in through the browser, save to the per-user pool
+/freeflow cline accounts            # List saved Cline logins
+/freeflow cline logout              # Remove a saved Cline login
 /freeflow export [path] [--include-secrets]  # Save the relay pool to a file (default freeflow-relays.json; passwords left out unless asked)
 /freeflow import <path> [--merge|--replace] [--dry-run]  # Load a relay pool from a file (merge is default; replace asks first; dry-run previews only)
 ```
 
 ---
 
-### 27 models, one command
+### 31 models, one command
 
 ```bash
 /model → freeflow → pick
@@ -229,6 +232,17 @@ Keyless access. Short aliases work for every row (the full ID is in parentheses)
 
 \* Levels are forwarded as-is through the OpenRouter-style nested `reasoning` parameter; effort mapping is decided by each model. MiMo collapses `minimal→low` and `xhigh→high` upstream, so its selector shows 5 labels but only 3 distinct effort values.
 
+#### Cline (4 models), OpenAI compatible
+
+Rotating per-account promo, direct only (never through the relay pool). Sign in through your browser with `/freeflow cline login`, manage with `/freeflow cline accounts` and `/freeflow cline logout`. Requests roll across saved logins when one hits its daily free limit.
+
+| Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `cline-free/deepseek-v4.1-flash` | DeepSeek | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `cline-free/muse-spark-1.3-contributor` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal…xhigh`\* | ✅ |
+| `z-ai/glm-5.3-flash` | Zhipu AI | **262K** (262.144) | **64K** (65.536) | `minimal…xhigh`\* | ❌ |
+| `cline-free/solar-pro4` | Upstage | **131K** (131.072) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+
 ---
 
 ### Logs and debugging
@@ -254,7 +268,7 @@ About 19k lines including tests. The full suite (sandboxed, network-mocked) and
 ### FAQ
 
 **Do I need API keys?**
-No. Kilo uses a shared free credential and OpenCode free models need no header. You never paste a key.
+No. Kilo uses a shared free credential and OpenCode free models need no header. You never paste a key. Cline free models need a browser login instead: `/freeflow cline login` saves it to a per-user pool on your machine.
 
 **What if all relays hit rate limits?**
 The proxy tries direct upstream. If that is also rate-limited, the host shows the limit. That number is the shared upstream cap; without relays you would hit the same wall sooner.
@@ -322,7 +336,7 @@ pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```
 src/
 ├── index.ts          # extension entry, lifecycle hooks
-├── models.ts         # 27-model catalog definitions
+├── models.ts         # 31-model catalog definitions
 ├── catalog.ts        # model catalog cache (24h disk)
 ├── proxy.ts          # local proxy server (127.0.0.1:28180)
 ├── relay.ts          # relay selection and round-robin

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",

package/src/cline-accounts.ts

@@ -30,6 +30,14 @@ export interface ClineAccount {
  token: string;
  addedAt: string;
  lastOkAt?: number;
+ /** WorkOS refresh token for device-login slots; absent on legacy key slots. */
+ refreshToken?: string;
+ /** Epoch-ms when `token` expires; absent means "no known expiry" (legacy slots). */
+ expiresAt?: number;
+ /** WorkOS account id, kept for display/diagnostics only. */
+ accountId?: string;
+ /** Login email, kept for display/diagnostics only. */
+ email?: string;
 }
 
 export interface ClinePoolState {
@@ -37,6 +45,31 @@ export interface ClinePoolState {
  activeSlot?: string;
 }
 
+/**
+ * Fresh tokens minted via the device-login refresh flow. DeviceAuth owns the
+ * network call; this module only applies the result to the pool file.
+ */
+export interface ClineRefreshResult {
+ token: string;
+ refreshToken?: string;
+ expiresAt?: number;
+ accountId?: string;
+ email?: string;
+}
+
+/**
+ * Refresh one slot. Resolves to the fresh tokens, or null when the grant is
+ * dead (invalid_grant — the slot must be logged in again). May throw on
+ * transient network faults; callers treat a throw as "keep the stale token".
+ */
+export type ClineRefresher = (refreshToken: string) => Promise<ClineRefreshResult | null>;
+
+/** Usable bearer for one slot, resolved via refresh when stale. */
+export interface ValidSlotCredentials {
+ slot: string;
+ token: string;
+}
+
 /** Cooldowns after failures so a bad key stops absorbing traffic. */
 const AUTH_COOLDOWN_MS = 10 * 60_000;
 const RATE_COOLDOWN_MS = 90_000;
@@ -112,11 +145,25 @@ function readPoolFile(): ClinePoolState {
    const slot = typeof rec.slot === "string" ? rec.slot.trim() : "";
    const token = typeof rec.token === "string" ? rec.token : "";
    if (!slot || !token.startsWith("workos:")) continue;
+   const refreshRaw: unknown = rec.refreshToken;
+   const refreshToken = typeof refreshRaw === "string" && refreshRaw.length > 0 ? refreshRaw : undefined;
+   const expiresRaw: unknown = rec.expiresAt;
+   const expiresAt = typeof expiresRaw === "number" && Number.isFinite(expiresRaw) && expiresRaw > 0
+    ? expiresRaw
+    : undefined;
+   const accountIdRaw: unknown = rec.accountId;
+   const accountId = typeof accountIdRaw === "string" && accountIdRaw.trim() ? accountIdRaw.trim() : undefined;
+   const emailRaw: unknown = rec.email;
+   const email = typeof emailRaw === "string" && emailRaw.trim() ? emailRaw.trim() : undefined;
    accounts.push({
     slot,
     token,
     addedAt: typeof rec.addedAt === "string" ? rec.addedAt : new Date().toISOString(),
     ...(typeof rec.lastOkAt === "number" ? { lastOkAt: rec.lastOkAt } : {}),
+    ...(refreshToken ? { refreshToken } : {}),
+    ...(expiresAt !== undefined ? { expiresAt } : {}),
+    ...(accountId ? { accountId } : {}),
+    ...(email ? { email } : {}),
    });
   }
   const activeRaw: unknown = doc.activeSlot;
@@ -180,8 +227,14 @@ export function redactedToken(token: string): string {
 /**
  * Save (or replace) one login slot. The token must carry the `workos:` prefix.
  * Throws on bad input — the message never echoes the token.
+ * Extras carry the device-login grant (refresh token, expiry, identity);
+ * legacy key slots keep calling with two args and load untouched.
  */
-export function addAccount(slot: string, token: string): ClinePoolState {
+export function addAccount(
+ slot: string,
+ token: string,
+ extras?: { refreshToken?: string; expiresAt?: number; accountId?: string; email?: string },
+): ClinePoolState {
  const cleanSlot = (slot || "").trim();
  if (!cleanSlot) throw new Error("Cline slot name cannot be empty");
  if (cleanSlot.length > 64) throw new Error("Cline slot name is too long (max 64 characters)");
@@ -190,8 +243,31 @@ export function addAccount(slot: string, token: string): ClinePoolState {
  const existing = pool.accounts.find((a) => a.slot === cleanSlot);
  if (existing) {
   existing.token = token;
+  if (extras?.refreshToken) existing.refreshToken = extras.refreshToken;
+  if (extras?.expiresAt !== undefined) {
+   if (Number.isFinite(extras.expiresAt) && extras.expiresAt > 0) existing.expiresAt = extras.expiresAt;
+   else delete existing.expiresAt;
+  }
+  if (extras?.accountId !== undefined) {
+   if (extras.accountId.trim()) existing.accountId = extras.accountId.trim();
+   else delete existing.accountId;
+  }
+  if (extras?.email !== undefined) {
+   if (extras.email.trim()) existing.email = extras.email.trim();
+   else delete existing.email;
+  }
  } else {
-  pool.accounts.push({ slot: cleanSlot, token, addedAt: new Date().toISOString() });
+  pool.accounts.push({
+   slot: cleanSlot,
+   token,
+   addedAt: new Date().toISOString(),
+   ...(extras?.refreshToken ? { refreshToken: extras.refreshToken } : {}),
+   ...(extras?.expiresAt !== undefined && Number.isFinite(extras.expiresAt) && extras.expiresAt > 0
+    ? { expiresAt: extras.expiresAt }
+    : {}),
+   ...(extras?.accountId?.trim() ? { accountId: extras.accountId.trim() } : {}),
+   ...(extras?.email?.trim() ? { email: extras.email.trim() } : {}),
+  });
  }
  if (!pool.activeSlot) pool.activeSlot = cleanSlot;
  slotCooldowns.delete(cleanSlot);
@@ -199,6 +275,79 @@ export function addAccount(slot: string, token: string): ClinePoolState {
  return pool;
 }
 
+/** Skew so a token expiring mid-flight counts as stale before it breaks a call. */
+export const CLINE_REFRESH_SKEW_MS = 60_000;
+
+/**
+ * True when the slot carries a known expiry that has passed (or passes within
+ * the skew window). Slots without `expiresAt` — every legacy key slot — are
+ * never stale: they load and serve exactly as before.
+ */
+export function isClineTokenStale(account: ClineAccount, skewMs = CLINE_REFRESH_SKEW_MS): boolean {
+ if (typeof account.expiresAt !== "number" || !Number.isFinite(account.expiresAt)) return false;
+ return Date.now() + skewMs >= account.expiresAt;
+}
+
+/**
+ * Refresh outcome for one slot: fresh tokens applied and persisted (`true`),
+ * dead grant with nothing to keep (`false`), or a transient fault where the
+ * caller should fall back to the stale bearer (`null`).
+ */
+async function refreshAccountInPlace(
+ pool: ClinePoolState,
+ account: ClineAccount,
+ refreshImpl: ClineRefresher,
+): Promise<boolean | null> {
+ const current = account.refreshToken;
+ if (!current) return null;
+ let fresh: ClineRefreshResult | null;
+ try {
+  fresh = await refreshImpl(current);
+ } catch (e) {
+  logWarn("cline slot refresh failed — keeping stale bearer", { slot: account.slot });
+  void e;
+  return null;
+ }
+ if (!fresh || typeof fresh.token !== "string" || !fresh.token.startsWith("workos:")) {
+  logWarn("cline slot refresh rejected — grant is dead", { slot: account.slot });
+  return false;
+ }
+ account.token = fresh.token;
+ if (fresh.refreshToken) account.refreshToken = fresh.refreshToken;
+ if (typeof fresh.expiresAt === "number" && Number.isFinite(fresh.expiresAt) && fresh.expiresAt > 0) {
+  account.expiresAt = fresh.expiresAt;
+ } else {
+  delete account.expiresAt;
+ }
+ if (fresh.accountId?.trim()) account.accountId = fresh.accountId.trim();
+ if (fresh.email?.trim()) account.email = fresh.email.trim();
+ savePool(pool);
+ return true;
+}
+
+/**
+ * Resolve a usable bearer for one slot. Fresh slots and legacy slots without
+ * a known expiry return immediately; stale slots with a refresh grant try one
+ * refresh and persist it. Resolves null when the slot is unknown or its grant
+ * is dead (invalid_grant) — the caller should prompt for a fresh login.
+ */
+export async function getValidSlotCredentials(
+ slot: string,
+ opts?: { refreshImpl?: ClineRefresher; skewMs?: number },
+): Promise<ValidSlotCredentials | null> {
+ const cleanSlot = (slot || "").trim();
+ if (!cleanSlot) return null;
+ const pool = loadPool();
+ const account = pool.accounts.find((a) => a.slot === cleanSlot);
+ if (!account) return null;
+ if (!isClineTokenStale(account, opts?.skewMs)) return { slot: account.slot, token: account.token };
+ if (!account.refreshToken || !opts?.refreshImpl) return { slot: account.slot, token: account.token };
+ const outcome = await refreshAccountInPlace(pool, account, opts.refreshImpl);
+ if (outcome === true) return { slot: account.slot, token: account.token };
+ if (outcome === false) return null;
+ return { slot: account.slot, token: account.token };
+}
+
 /** Drop one login slot. Returns false when the slot was not saved. */
 export function removeAccount(slot: string): boolean {
  const cleanSlot = (slot || "").trim();
@@ -221,6 +370,12 @@ export interface ClineRollOpts {
  slots?: string[];
  fetchImpl?: typeof fetch;
  reqId?: string;
+ /**
+  * Device-login refresher. When present, a stale slot refreshes once before
+  * its attempt, and a 401/403 refreshes once before the slot cools out.
+  * Absent: every slot serves its stored bearer exactly as before.
+  */
+ refreshImpl?: ClineRefresher;
 }
 
 export interface ClineRollResult {
@@ -265,40 +420,81 @@ export async function rollChat(opts: ClineRollOpts): Promise<ClineRollResult> {
   return { res: exhaustedResponse(reason), slot: null, exhausted: true, kind: "exhausted" };
  }
  for (const account of candidates) {
-  const token = account.token;
-  let res: Response;
-  try {
-   res = await fetchImpl(opts.chatUrl, {
-    method: "POST",
-    headers: {
-     "content-type": "application/json",
-     authorization: `Bearer ${token}`,
-    },
-    body: opts.body,
-   });
-  } catch (e) {
-   markSlotCooldown(account.slot, DEFAULT_COOLDOWN_MS);
-   logWarn("cline slot fetch error — cooling slot", { slot: account.slot });
-   void e;
-   continue;
+  // Stale device-login bearer: one refresh before the attempt. A dead grant
+  // cools the slot out immediately; a transient fault keeps the stale token.
+  let refreshedThisSlot = false;
+  if (opts.refreshImpl && account.refreshToken && isClineTokenStale(account)) {
+   const outcome = await refreshAccountInPlace(pool, account, opts.refreshImpl);
+   if (outcome === false) {
+    markSlotCooldown(account.slot, AUTH_COOLDOWN_MS);
+    logWarn("cline slot refresh rejected — cooling slot", { slot: account.slot });
+    continue;
+   }
+   refreshedThisSlot = outcome === true;
   }
-  const kind = mapClineError(res.status);
-  if (kind === "ok" || kind === "client") {
+  const attempt = async (token: string): Promise<Response | null> => {
+   try {
+    return await fetchImpl(opts.chatUrl, {
+     method: "POST",
+     headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${token}`,
+     },
+     body: opts.body,
+    });
+   } catch (e) {
+    markSlotCooldown(account.slot, DEFAULT_COOLDOWN_MS);
+    logWarn("cline slot fetch error — cooling slot", { slot: account.slot });
+    void e;
+    return null;
+   }
+  };
+  const succeed = (res: Response, kind: ClineErrorKind): ClineRollResult => {
    if (kind === "ok") {
     account.lastOkAt = Date.now();
     pool.activeSlot = account.slot;
     savePool(pool);
    }
    return { res, slot: account.slot, exhausted: false, kind };
+  };
+  const cool = (kind: ClineErrorKind, status: number): void => {
+   markSlotCooldown(
+    account.slot,
+    kind === "auth" ? AUTH_COOLDOWN_MS : kind === "rate-limit" ? RATE_COOLDOWN_MS : SERVER_COOLDOWN_MS,
+   );
+   logWarn("cline slot failed — rolling to next slot", { slot: account.slot, status });
+  };
+  let res = await attempt(account.token);
+  if (!res) continue;
+  let kind = mapClineError(res.status);
+  if (kind === "ok" || kind === "client") return succeed(res, kind);
+  // Auth failure on a refreshable slot that has not refreshed yet: one
+  // refresh, then exactly one retry with the fresh bearer.
+  if (kind === "auth" && !refreshedThisSlot && opts.refreshImpl && account.refreshToken) {
+   try {
+    await res.body?.cancel();
+   } catch { }
+   const outcome = await refreshAccountInPlace(pool, account, opts.refreshImpl);
+   if (outcome === true) {
+    refreshedThisSlot = true;
+    res = await attempt(account.token);
+    if (!res) continue;
+    kind = mapClineError(res.status);
+    if (kind === "ok" || kind === "client") return succeed(res, kind);
+   } else if (outcome === false) {
+    try {
+     await res.body?.cancel();
+    } catch { }
+    cool(kind, res.status);
+    continue;
+   }
+   // Transient refresh fault: fall through and cool the slot on the
+   // original auth result below.
   }
-  markSlotCooldown(
-   account.slot,
-   kind === "auth" ? AUTH_COOLDOWN_MS : kind === "rate-limit" ? RATE_COOLDOWN_MS : SERVER_COOLDOWN_MS,
-  );
+  cool(kind, res.status);
   try {
    await res.body?.cancel();
   } catch { }
-  logWarn("cline slot failed — rolling to next slot", { slot: account.slot, status: res.status });
  }
  logWarn("cline pool exhausted after roll", { slots: candidates.length });
  return {

package/src/cline-device-auth.ts

@@ -0,0 +1,335 @@
+/**
+ * Cline WorkOS device-flow auth (extension login, no paste).
+ * Mirrors C:/tmp/cline-login-proto/src/cline-auth.ts + reference/cline
+ * sdk/packages/core/src/auth/cline.ts (device authorize / poll /
+ * register / refresh) and provider-auth-registry.ts (expiry derive,
+ * workos: prefix). All network goes through injectable fetchImpl;
+ * mocked tests only, no live calls here.
+ */
+
+export interface OAuthCredentials {
+ access: string;
+ refresh: string;
+ /** Expiration timestamp in milliseconds since epoch. */
+ expires: number;
+ accountId?: string;
+ email?: string;
+ metadata?: Record<string, unknown>;
+}
+
+export interface DeviceAuth {
+ deviceCode: string;
+ userCode: string;
+ verificationUri: string;
+ verificationUriComplete?: string;
+ expiresIn: number;
+ interval: number;
+}
+
+export interface DevicePollTokens {
+ accessToken: string;
+ refreshToken: string;
+}
+
+export interface PollOptions {
+ timeoutMs?: number;
+ maxWaitMs?: number;
+ fetchImpl?: FetchImpl;
+ /** Cooperative cancel from the login UI (esc / timeout). */
+ signal?: AbortSignal;
+}
+
+export const DEFAULT_WORKOS_BASE = "https://api.workos.com";
+export const DEFAULT_API_BASE = "https://api.cline.bot";
+export const WORKOS_TOKEN_PREFIX = "workos:";
+
+/** Env override for the WorkOS client id (wins over the bundled default). */
+export const CLINE_WORKOS_CLIENT_ID_ENV = "PI_FREEFLOW_CLINE_WORKOS_CLIENT_ID";
+
+/**
+ * Bundled production client id (reference shared/src/runtime/cline-environment.ts,
+ * production entry). Env override wins when set and non-blank.
+ */
+export const BUNDLED_CLINE_WORKOS_CLIENT_ID = "client_01K3A541FN8TA3EPPHTD2325AR";
+
+export function resolveClineWorkosClientId(): string {
+ const fromEnv = process.env[CLINE_WORKOS_CLIENT_ID_ENV]?.trim();
+ if (fromEnv) return fromEnv;
+ return BUNDLED_CLINE_WORKOS_CLIENT_ID;
+}
+
+/** Resolved client id used by start/poll. */
+export const CLINE_WORKOS_CLIENT_ID = resolveClineWorkosClientId();
+
+export function toApiKey(accessToken: string): string {
+ const token = accessToken.trim();
+ return token.toLowerCase().startsWith(WORKOS_TOKEN_PREFIX) ? token : `${WORKOS_TOKEN_PREFIX}${token}`;
+}
+
+const DEVICE_AUTHORIZATION_PATH = "/user_management/authorize/device";
+const AUTHENTICATE_PATH = "/user_management/authenticate";
+const REGISTER_PATH = "/api/v1/auth/register";
+const REFRESH_PATH = "/api/v1/auth/refresh";
+
+const HTTP_TIMEOUT_MS = 30 * 1000;
+
+export type FetchImpl = typeof fetch;
+
+function joinUrl(base: string, path: string): string {
+ return base.replace(/\/+$/, "") + path;
+}
+
+export class ClineAuthError extends Error {
+ readonly status?: number;
+ readonly errorCode?: string;
+ constructor(message: string, opts?: { status?: number; errorCode?: string }) {
+  super(message);
+  this.name = "ClineAuthError";
+  this.status = opts?.status;
+  this.errorCode = opts?.errorCode;
+ }
+}
+
+function toEpochMs(isoDateTime: string): number {
+ const epoch = Date.parse(isoDateTime);
+ if (Number.isNaN(epoch)) {
+  throw new Error(`Invalid expiresAt value: ${isoDateTime}`);
+ }
+ return epoch;
+}
+
+function toSeconds(value: unknown, fallback: number): number {
+ if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+ return fallback;
+}
+
+function decodeJwtExpMs(accessToken: string): number | null {
+ try {
+  const parts = accessToken.split(".");
+  if (parts.length < 2) return null;
+  const payload = JSON.parse(
+   Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"),
+  ) as { exp?: unknown };
+  if (typeof payload.exp === "number" && payload.exp > 0) return payload.exp * 1000;
+  return null;
+ } catch {
+  return null;
+ }
+}
+
+// Expiry derivation order (per registry deriveCredentialExpiry):
+// explicit server expiry -> JWT exp claim -> already-expired (forces refresh).
+export function deriveExpiry(explicitMs: number | undefined, accessToken: string): number {
+ if (typeof explicitMs === "number" && Number.isFinite(explicitMs) && explicitMs > 0) return explicitMs;
+ return decodeJwtExpMs(accessToken) ?? Date.now() - 1;
+}
+
+export async function startDeviceAuth(
+ workosBase: string = DEFAULT_WORKOS_BASE,
+ fetchImpl: FetchImpl = fetch,
+): Promise<DeviceAuth> {
+ const response = await fetchImpl(joinUrl(workosBase, DEVICE_AUTHORIZATION_PATH), {
+  method: "POST",
+  headers: { "Content-Type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams({ client_id: resolveClineWorkosClientId() }),
+  signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+ });
+ const json = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+ if (!response.ok) {
+  throw new ClineAuthError(
+   `Device authorization failed: ${response.status}` +
+   (typeof json.error_description === "string" ? ` - ${json.error_description}` : ""),
+   { status: response.status, errorCode: typeof json.error === "string" ? json.error : undefined },
+  );
+ }
+ if (
+  typeof json.device_code !== "string" ||
+  typeof json.user_code !== "string" ||
+  typeof json.verification_uri !== "string"
+ ) {
+  throw new Error("Invalid WorkOS device authorization response");
+ }
+ return {
+  deviceCode: json.device_code,
+  userCode: json.user_code,
+  verificationUri: json.verification_uri,
+  verificationUriComplete:
+   typeof json.verification_uri_complete === "string" ? json.verification_uri_complete : undefined,
+  expiresIn: toSeconds(json.expires_in, 300),
+  interval: toSeconds(json.interval, 5),
+ };
+}
+
+function throwDenied(payload: Record<string, unknown>, status: number, fallback: string): never {
+ const code = typeof payload.error === "string" ? payload.error : undefined;
+ const detail = typeof payload.error_description === "string" ? payload.error_description : fallback;
+ throw new ClineAuthError(detail, { status, errorCode: code });
+}
+
+export async function pollDeviceToken(
+ workosBase: string = DEFAULT_WORKOS_BASE,
+ deviceCode = "",
+ intervalSeconds = 5,
+ options?: PollOptions,
+): Promise<DevicePollTokens> {
+ if (!deviceCode) throw new Error("deviceCode is required");
+ const fetchFn = options?.fetchImpl ?? fetch;
+ const outerSignal = options?.signal;
+ const deadline = Date.now() + (options?.maxWaitMs ?? intervalSeconds * 1000 * 60 * 10);
+ let interval = Math.max(1, intervalSeconds);
+ for (; ;) {
+  if (outerSignal?.aborted) {
+   throw new ClineAuthError("Device login cancelled", { errorCode: "cancelled" });
+  }
+  let response: Response;
+  try {
+   response = await fetchFn(joinUrl(workosBase, 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: deviceCode,
+     client_id: resolveClineWorkosClientId(),
+    }),
+    signal: AbortSignal.timeout(options?.timeoutMs ?? HTTP_TIMEOUT_MS),
+   });
+  } catch (error) {
+   if (outerSignal?.aborted) {
+    throw new ClineAuthError("Device login cancelled", { errorCode: "cancelled" });
+   }
+   if (error instanceof ClineAuthError) throw error;
+   if (Date.now() > deadline) throw new Error("WorkOS device authorization timed out");
+   await sleepMs(interval * 1000, outerSignal);
+   continue;
+  }
+  const payload = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+  if (response.ok) {
+   if (typeof payload.access_token !== "string" || typeof payload.refresh_token !== "string") {
+    throw new Error("Invalid WorkOS token response");
+   }
+   return { accessToken: payload.access_token, refreshToken: payload.refresh_token };
+  }
+  if (payload.error === "authorization_pending") {
+   // keep polling at the current interval
+  } else if (payload.error === "slow_down") {
+   interval += 1;
+  } else if (
+   payload.error === "access_denied" ||
+   payload.error === "expired_token" ||
+   payload.error === "invalid_grant"
+  ) {
+   throwDenied(payload, response.status, `Device login refused (${String(payload.error)})`);
+  } else {
+   throw new ClineAuthError(
+    typeof payload.error_description === "string"
+     ? String(payload.error_description)
+     : `WorkOS token polling failed: ${response.status}`,
+    { status: response.status, errorCode: typeof payload.error === "string" ? payload.error : undefined },
+   );
+  }
+  if (Date.now() > deadline) throw new Error("WorkOS device authorization timed out");
+  await sleepMs(interval * 1000, outerSignal);
+ }
+}
+
+async function sleepMs(ms: number, signal?: AbortSignal): Promise<void> {
+ if (signal?.aborted) throw new ClineAuthError("Device login cancelled", { errorCode: "cancelled" });
+ if (!signal) {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  await promise;
+  return;
+ }
+ const { promise, resolve, reject } = Promise.withResolvers<void>();
+ const onAbort = (): void => {
+  clearTimeout(timer);
+  reject(new ClineAuthError("Device login cancelled", { errorCode: "cancelled" }));
+ };
+ const timer = setTimeout(() => {
+  signal.removeEventListener("abort", onAbort);
+  resolve();
+ }, ms);
+ signal.addEventListener("abort", onAbort, { once: true });
+ await promise;
+}
+
+interface ClineTokenData {
+ accessToken: string;
+ refreshToken?: string;
+ tokenType: string;
+ expiresAt: string;
+ userInfo: { email: string; clineUserId: string | null };
+}
+
+function toCredentials(data: ClineTokenData, fallbackRefresh?: string): OAuthCredentials {
+ const refresh = data.refreshToken ?? fallbackRefresh;
+ if (!refresh) throw new Error("Token response did not include a refresh token");
+ let explicit: number | undefined;
+ try {
+  explicit = toEpochMs(data.expiresAt);
+ } catch {
+  explicit = undefined;
+ }
+ return {
+  access: data.accessToken,
+  refresh,
+  expires: deriveExpiry(explicit, data.accessToken),
+  accountId: data.userInfo.clineUserId ?? undefined,
+  email: data.userInfo.email || undefined,
+  metadata: { tokenType: data.tokenType },
+ };
+}
+
+async function readTokenData(response: Response, message: string): Promise<ClineTokenData> {
+ const json = (await response.json().catch(() => ({}))) as {
+  success?: boolean;
+  data?: ClineTokenData;
+ };
+ if (!json.success || !json.data?.accessToken) {
+  throw new Error(`Invalid token response: ${message}`);
+ }
+ return json.data;
+}
+
+export async function registerClineToken(
+ apiBase: string = DEFAULT_API_BASE,
+ accessToken = "",
+ refreshToken = "",
+ fetchImpl: FetchImpl = fetch,
+): Promise<OAuthCredentials> {
+ if (!accessToken || !refreshToken) throw new Error("accessToken and refreshToken are required");
+ const response = await fetchImpl(joinUrl(apiBase, REGISTER_PATH), {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ accessToken, refreshToken }),
+  signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+ });
+ if (!response.ok) {
+  const text = await response.text().catch(() => "");
+  throw new ClineAuthError(`Token registration failed: ${response.status}${text ? ` - ${text}` : ""}`, {
+   status: response.status,
+  });
+ }
+ return toCredentials(await readTokenData(response, "register"));
+}
+
+export async function refreshClineToken(
+ apiBase: string = DEFAULT_API_BASE,
+ refreshToken = "",
+ fetchImpl: FetchImpl = fetch,
+): Promise<OAuthCredentials> {
+ if (!refreshToken) throw new Error("refreshToken is required");
+ const response = await fetchImpl(joinUrl(apiBase, REFRESH_PATH), {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ refreshToken, grantType: "refresh_token" }),
+  signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+ });
+ if (!response.ok) {
+  const text = await response.text().catch(() => "");
+  throw new ClineAuthError(`Token refresh failed: ${response.status}${text ? ` - ${text}` : ""}`, {
+   status: response.status,
+  });
+ }
+ return toCredentials(await readTokenData(response, "refresh"), refreshToken);
+}

package/src/commands.ts

@@ -59,6 +59,8 @@ import {
  formatRelayStatusLabel,
 } from "./relay-state.ts";
 import { addAccount, isClineSlotHealthy, loadPool, redactedToken, removeAccount } from "./cline-accounts.ts";
+import type { ClinePoolState } from "./cline-accounts.ts";
+import { pollDeviceToken, registerClineToken, startDeviceAuth, toApiKey } from "./cline-device-auth.ts";
 import type {
  ExtensionAPI,
  ExtensionContext,
@@ -348,20 +350,45 @@ function startLogsFollow(
  logsFollowTimer.unref?.();
 }
 
+/**
+ * Pick the login slot when the user gives none: "default" for the first
+ * login, then the smallest free "slot-2", "slot-3", … — never overwriting
+ * a saved login. Pure — takes the pool, returns a name.
+ */
+function nextClineSlot(pool: ClinePoolState): string {
+ if (!pool.accounts.some((a) => a.slot === "default")) return "default";
+ let n = 2;
+ while (pool.accounts.some((a) => a.slot === `slot-${n}`)) n += 1;
+ return `slot-${n}`;
+}
+
+/** One notify-ready line per saved login, in pool order. */
+function formatClineAccountLines(pool: ClinePoolState): string[] {
+ return pool.accounts.map((a, idx) => {
+  const star = a.slot === pool.activeSlot ? "*" : " ";
+  const health = isClineSlotHealthy(a.slot) ? "ready" : "cooling";
+  return `${star} [${idx + 1}] [${a.slot}] key ending ${redactedToken(a.token)} — ${health}`;
+ });
+}
+/** User-safe one-line message for caught values (never echoes secrets). */
+function clineErrorMessage(e: unknown): string {
+ if (e instanceof Error && e.message) return e.message;
+ if (typeof e === "string" && e) return e;
+ return "unknown error";
+}
 export function createCommandSpec(
  _pi: ExtensionAPI,
  onCatalogRefreshed?: (models: RegisteredModel[]) => void,
 ): Omit<RegisteredCommand, "name"> {
  return {
   description:
-   "Relay egress: auto | on | off | hide | show | widget hide/show | status | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | test [target|opencode] [--chat] | export [path] [--include-secrets] | import <path> [--merge|--replace] [--dry-run] | logs [level] [n] | debug on|off | refresh | update | deploy vercel | deploy cloudflare | deploy deno | install-startup | uninstall-startup | cline login [slot] | cline accounts | cline logout [slot]",
+   "Relay egress: auto | on | off | hide | show | widget hide/show | status | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | test [target|opencode] [--chat] | export [path] [--include-secrets] | import <path> [--merge|--replace] [--dry-run] | logs [level] [n] | debug on|off | refresh | update | deploy vercel | deploy cloudflare | deploy deno | install-startup | uninstall-startup | cline login [--key] [slot] | cline accounts | cline logout [slot]",
   getArgumentCompletions: (prefix: string) =>
    [
     "auto",
     "on",
     "off",
     "hide",
-    "show",
     "widget hide",
     "widget show",
     "status",
@@ -384,6 +411,7 @@ export function createCommandSpec(
     "uninstall-startup",
     "cline",
     "cline login",
+    "cline login --key",
     "cline accounts",
     "cline logout",
     "refresh",
@@ -1399,17 +1427,72 @@ export function createCommandSpec(
     const action = (tokens[0] || "accounts").toLowerCase();
     const arg = tokens.slice(1).join(" ").trim();
     if (action === "login") {
-     const slot = arg || ((await ctx.ui.input("Cline slot name (empty = default):", "default"))?.trim() || "default");
-     const token = ((await ctx.ui.input(`Paste the API key for Cline slot [${slot}]:`, ""))?.trim() || "");
-     if (!token) {
-      ctx.ui.notify("Cancelled — no API key provided", "warning");
-     } else {
-      try {
-       addAccount(slot, token);
-       ctx.ui.notify(`Saved Cline login [${slot}] (key ending ${redactedToken(token)}) — free Cline models are ready to use`, "info");
-      } catch (e) {
-       ctx.ui.notify((e as Error).message, "warning");
+     const raw = tokens.slice(1);
+     const pasteMode = raw.some((t) => t === "--key");
+     const slotArg = raw.filter((t) => t !== "--key").join(" ").trim();
+     if (pasteMode) {
+      // Manual fallback: paste a workos: API key (never shown back).
+      const slot = slotArg || ((await ctx.ui.input("Cline slot name (empty = default):", "default"))?.trim() || "default");
+      const token = ((await ctx.ui.input(`Paste the API key for Cline slot [${slot}]:`, ""))?.trim() || "");
+      if (!token) {
+       ctx.ui.notify("Cancelled — no API key provided", "warning");
+      } else {
+       try {
+        addAccount(slot, token);
+        ctx.ui.notify(`Saved Cline login [${slot}] (key ending ${redactedToken(token)}) — free Cline models are ready to use`, "info");
+       } catch (e) {
+        ctx.ui.notify((e as Error).message, "warning");
+       }
+      }
+      return;
+     }
+     // Device login inside the extension: approve in the browser, no paste.
+     const slot = slotArg || nextClineSlot(loadPool());
+     let started;
+     try {
+      started = await startDeviceAuth();
+     } catch (e) {
+      ctx.ui.notify(`Could not reach Cline to start login: ${clineErrorMessage(e)}`, "error");
+      return;
+     }
+     const link = started.verificationUriComplete ?? started.verificationUri;
+     const minutes = Math.max(1, Math.round(started.expiresIn / 60));
+     ctx.ui.notify(`Cline login [${slot}]: open ${link} and enter code ${started.userCode} (expires in ~${minutes} min)`, "info");
+     ctx.ui.notify("Waiting for approval in the browser — approve or cancel there; this finishes on its own.", "info");
+     const progress = setInterval(() => {
+      ctx.ui.notify("Still waiting for Cline approval — approve or cancel in the browser.", "info");
+     }, 45000);
+     // @ts-ignore allow unref to not block process exit in CLI
+     progress.unref?.();
+     try {
+      const deviceTokens = await pollDeviceToken(undefined, started.deviceCode, started.interval);
+      const creds = await registerClineToken(undefined, deviceTokens.accessToken, deviceTokens.refreshToken);
+      const apiKey = toApiKey(creds.access);
+      addAccount(slot, apiKey, {
+       refreshToken: creds.refresh,
+       expiresAt: creds.expires,
+       ...(creds.accountId ? { accountId: creds.accountId } : {}),
+       ...(creds.email ? { email: creds.email } : {}),
+      });
+      ctx.ui.notify(`Saved Cline login [${slot}] (key ending ${redactedToken(apiKey)}) — free Cline models are ready to use`, "info");
+      const pool = loadPool();
+      ctx.ui.notify(`Cline logins (${pool.accounts.length}):\n${formatClineAccountLines(pool).join("\n")}`, "info");
+     } catch (e) {
+      let code: string | undefined;
+      if (e && typeof e === "object" && "errorCode" in e && typeof e.errorCode === "string") {
+       code = e.errorCode;
+      }
+      if (code === "authorization_pending") {
+       ctx.ui.notify("Still waiting for Cline approval — approve or cancel in the browser.", "info");
+      } else if (code === "access_denied" || code === "cancelled") {
+       ctx.ui.notify("Cline login cancelled.", "warning");
+      } else if (code === "expired_token") {
+       ctx.ui.notify("Cline login code expired — run /freeflow cline login again for a fresh code.", "warning");
+      } else {
+       ctx.ui.notify(`Cline login did not finish: ${clineErrorMessage(e)}`, "warning");
       }
+     } finally {
+      clearInterval(progress);
      }
     } else if (action === "accounts" || action === "list") {
      const pool = loadPool();
@@ -1433,7 +1516,7 @@ export function createCommandSpec(
       ctx.ui.notify(`Removed Cline login [${slot}]`, "info");
      }
     } else {
-     ctx.ui.notify("Usage: /freeflow cline login [slot] | /freeflow cline accounts | /freeflow cline logout [slot]", "warning");
+     ctx.ui.notify("Usage: /freeflow cline login [--key] [slot] | /freeflow cline accounts | /freeflow cline logout [slot]", "warning");
     }
    } else if (sub === "export") {
     const tokens = rest.trim() ? rest.trim().split(/\s+/) : [];