@tejasa97/pi-cline-free-provider 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tejasa97
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @tejasa97/pi-cline-free-provider
+
+Pi provider for Cline's **free** `z-ai/*` gateway models — including **GLM 5.3 Flash** — through the same Cline API the CLI uses.
+
+This complements [`pi-clinepass-provider`](https://www.npmjs.com/package/pi-clinepass-provider), which exposes paid ClinePass `cline-pass/*` models. Cline CLI users already get `z-ai/glm-5.3-flash` for free; this package brings that into Pi.
+
+## Install
+
+```sh
+pi install npm:@tejasa97/pi-cline-free-provider
+```
+
+Or from git:
+
+```sh
+pi install git:github.com/tejasa97/pi-cline-free-provider
+```
+
+Local clone:
+
+```sh
+pi install /absolute/path/to/pi-cline-free-provider
+```
+
+After install, add your preferred model to `enabledModels` in `~/.pi/agent/settings.json` if you use that whitelist:
+
+```json
+"clinefree/z-ai/glm-5.3-flash"
+```
+
+## Usage
+
+1. Sign in with the Cline CLI: `cline auth`
+2. In Pi: `/login` → **Cline Free** (optional if CLI auth is already present)
+3. Pick a model: `/model clinefree/z-ai/glm-5.3-flash`
+
+One-liner:
+
+```sh
+pi --model clinefree/z-ai/glm-5.3-flash
+```
+
+### Auth
+
+The provider reuses credentials from, in order:
+
+- `CLINE_API_KEY` env var
+- Cline CLI `~/.cline/data/settings/providers.json` (from `cline auth`)
+- Pi `~/.pi/agent/auth.json` (`clinefree` or `clinepass` OAuth)
+
+If you already use `pi-clinepass-provider`, your existing Cline CLI login works here too.
+
+### Static fallback models
+
+When `/api/v1/models` is unavailable, these are registered:
+
+| Model ID | Name |
+| --- | --- |
+| `z-ai/glm-5.3-flash` | GLM 5.3 Flash (Cline free) |
+| `z-ai/glm-5.2:free` | GLM 5.2 Free |
+| `z-ai/glm-4.7-flash` | GLM 4.7 Flash |
+
+When authenticated, the extension dynamically discovers all `z-ai/*` models from Cline's API (excluding batch and alias entries).
+
+## Testing
+
+```sh
+npm test
+npm run test:e2e   # requires pi + local install
+```
+
+## Related
+
+- [Cline CLI](https://docs.cline.bot/)
+- [pi-clinepass-provider](https://www.npmjs.com/package/pi-clinepass-provider) — paid ClinePass `cline-pass/*` catalog

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tejasa97/pi-cline-free-provider",
+  "version": "0.1.0",
+  "description": "Pi provider for Cline's free z-ai gateway models (GLM 5.3 Flash, GLM 5.2 Free, and more) via the Cline CLI subscription",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "tests",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "test:e2e": "bash tests/e2e/smoke.sh",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai",
+    "cline",
+    "cline-cli",
+    "glm",
+    "llm",
+    "pi",
+    "pi-coding-agent",
+    "pi-package",
+    "provider",
+    "z-ai"
+  ],
+  "license": "MIT",
+  "author": "tejasa97",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tejasa97/pi-cline-free-provider.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tejasa97/pi-cline-free-provider/issues"
+  },
+  "homepage": "https://github.com/tejasa97/pi-cline-free-provider#readme",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@types/node": "^26.0.1",
+    "tsx": "^4.20.5",
+    "typescript": "^7.0.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,48 @@
+import { isRecord, stringValue } from "./utils.js";
+import { ENV_API_KEY, WORKOS_TOKEN_PREFIX } from "./env.js";
+import { walkAuthPaths, walkClineProviderSettings, type AuthKeyOptions } from "./config-store.js";
+
+export {
+  defaultAuthPaths,
+  walkAuthPaths,
+  walkClineProviderSettings,
+  type AuthKeyOptions,
+} from "./config-store.js";
+
+const PI_AUTH_FIELDS = ["clinefree", "clinepass"] as const;
+
+function resolveClineProvidersKey(parsed: Record<string, unknown>): string | undefined {
+  return walkClineProviderSettings(parsed, (settings) => stringValue(settings.apiKey));
+}
+
+function resolvePiProviderApiKey(parsed: Record<string, unknown>): string | undefined {
+  for (const field of PI_AUTH_FIELDS) {
+    const value = parsed[field];
+    if (typeof value === "string") return value;
+    if (!isRecord(value)) continue;
+
+    const access = stringValue(value.access);
+    if (access && !access.startsWith(WORKOS_TOKEN_PREFIX)) return access;
+  }
+  return undefined;
+}
+
+export function resolveApiKey(
+  providedKey?: string,
+  options: AuthKeyOptions = {},
+): string | undefined {
+  if (providedKey) return providedKey;
+
+  const env = options.env ?? process.env;
+  if (env[ENV_API_KEY]) return env[ENV_API_KEY];
+
+  return walkAuthPaths(options, (parsed) => {
+    const clineKey = resolveClineProvidersKey(parsed);
+    if (clineKey) return clineKey;
+
+    const apiKey = stringValue(parsed.apiKey);
+    if (apiKey) return apiKey;
+
+    return resolvePiProviderApiKey(parsed);
+  });
+}

package/src/config-store.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isRecord } from "./utils.js";
+
+function isMissingAuthFileError(error: unknown): boolean {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const code = (error as { code?: unknown }).code;
+    if (code === "ENOENT") return true;
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return msg.includes("ENOENT") || msg.includes("not found");
+}
+
+export interface AuthKeyOptions {
+  env?: Record<string, string | undefined>;
+  authPaths?: readonly string[];
+  homeDir?: () => string;
+  readFile?: (path: string) => string;
+  fileExists?: (path: string) => boolean;
+}
+
+export function defaultAuthPaths(home: string): string[] {
+  return [
+    join(home, ".cline", "data", "settings", "providers.json"),
+    join(home, ".pi", "agent", "auth.json"),
+  ];
+}
+
+export function walkAuthPaths<T>(
+  options: AuthKeyOptions,
+  extract: (parsed: Record<string, unknown>) => T | undefined,
+): T | undefined {
+  const home = options.homeDir?.() ?? homedir();
+  const authPaths = options.authPaths ?? defaultAuthPaths(home);
+  const readFile = options.readFile ?? ((p: string) => readFileSync(p, "utf-8"));
+  const fileExists = options.fileExists ?? ((p: string) => existsSync(p));
+
+  for (const authPath of authPaths) {
+    let parsed: unknown;
+    try {
+      if (!fileExists(authPath)) continue;
+      parsed = JSON.parse(readFile(authPath));
+    } catch (e) {
+      if (!isMissingAuthFileError(e)) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.warn(`[clinefree] Warning: failed to read auth file ${authPath}: ${msg}`);
+      }
+      continue;
+    }
+
+    if (!isRecord(parsed)) continue;
+
+    const result = extract(parsed);
+    if (result !== undefined) return result;
+  }
+  return undefined;
+}
+
+export function walkClineProviderSettings<T>(
+  parsed: Record<string, unknown>,
+  extract: (settings: Record<string, unknown>) => T | undefined,
+): T | undefined {
+  if (!isRecord(parsed)) return undefined;
+  const providers = isRecord(parsed.providers) ? parsed.providers : undefined;
+  if (!providers) return undefined;
+
+  for (const key of ["cline-pass", "cline"]) {
+    const provider = isRecord(providers[key]) ? providers[key] : undefined;
+    if (!provider) continue;
+    const settings = isRecord(provider.settings) ? provider.settings : undefined;
+    if (!settings) continue;
+    const result = extract(settings);
+    if (result !== undefined) return result;
+  }
+  return undefined;
+}

package/src/env.ts

@@ -0,0 +1,26 @@
+export const DEFAULT_API_BASE = "https://api.cline.bot";
+export const ENV_API_KEY = "CLINE_API_KEY";
+export const WORKOS_TOKEN_PREFIX = "workos:";
+export const PROVIDER_NAME = "clinefree";
+
+export function resolveApiBase(env: Record<string, string | undefined> = process.env): string {
+  const base = env.CLINE_API_BASE?.trim();
+  if (!base) return DEFAULT_API_BASE;
+  return base.replace(/\/+$/, "");
+}
+
+const CONTROL_CHARS_RE = new RegExp(
+  `[${String.fromCharCode(0)}-${String.fromCharCode(31)}${String.fromCharCode(127)}]`,
+  "g",
+);
+
+export function sanitizeApiKey(input: string): string {
+  const esc = "\x1b";
+  return input
+    .replaceAll(`${esc}[200~`, "")
+    .replaceAll(`${esc}[201~`, "")
+    .replaceAll("[200~", "")
+    .replaceAll("[201~", "")
+    .replace(CONTROL_CHARS_RE, "")
+    .trim();
+}

package/src/error-handler.ts

@@ -0,0 +1,32 @@
+import { classifyClineFreeError } from "./errors.js";
+import { PROVIDER_NAME } from "./env.js";
+
+export function handleClineFreeError(
+  event: { message: unknown },
+  ctx: {
+    hasUI: boolean;
+    ui: { notify: (msg: string, type: "info" | "warning" | "error") => void };
+    model?: { provider?: string };
+  },
+): void {
+  if (!event.message) return;
+
+  const msg = event.message as {
+    stopReason?: string;
+    errorMessage?: string;
+    provider?: string;
+  };
+
+  if (msg.stopReason !== "error" || !msg.errorMessage) return;
+
+  const provider = msg.provider ?? ctx.model?.provider;
+  if (provider !== PROVIDER_NAME) return;
+
+  const { message: friendlyMessage } = classifyClineFreeError(msg.errorMessage);
+
+  if (ctx.hasUI) {
+    ctx.ui.notify(friendlyMessage, "error");
+  } else {
+    console.error(`[clinefree] ${friendlyMessage}`);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,31 @@
+export type ClineFreeErrorType = "auth_expired" | "rate_limited" | "unknown";
+
+function matchesAny(text: string, patterns: string[]): boolean {
+  return patterns.some((p) => text.includes(p));
+}
+
+export const CLINEFREE_ERROR_MESSAGES: Record<ClineFreeErrorType, string> = {
+  auth_expired:
+    "Cline authentication expired. Run `pi /login` and select Cline Free, or run `cline auth` first.",
+  rate_limited:
+    "Cline rate limit reached. Wait a moment and try again.",
+  unknown:
+    "Cline request failed. Run `cline auth` or `pi /login` to refresh credentials.",
+};
+
+export function classifyClineFreeError(errorMessage: string): {
+  type: ClineFreeErrorType;
+  message: string;
+} {
+  const lower = errorMessage.toLowerCase();
+
+  if (matchesAny(lower, ["401", "unauthorized", "invalid api key", "invalid_api_key"])) {
+    return { type: "auth_expired", message: CLINEFREE_ERROR_MESSAGES.auth_expired };
+  }
+
+  if (matchesAny(lower, ["429", "rate limit", "too many requests", "rate_limit"])) {
+    return { type: "rate_limited", message: CLINEFREE_ERROR_MESSAGES.rate_limited };
+  }
+
+  return { type: "unknown", message: CLINEFREE_ERROR_MESSAGES.unknown };
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Cline Free provider for pi — free z-ai gateway models via Cline CLI auth.
+ *
+ * @module pi-cline-free-provider
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveApiKey } from "./auth.js";
+import { handleClineFreeError } from "./error-handler.js";
+import { createClineFreeProvider, loadModelCatalog } from "./provider.js";
+
+export default async function (pi: ExtensionAPI) {
+  const apiKey = resolveApiKey();
+  const models = await loadModelCatalog(apiKey);
+  pi.registerProvider(createClineFreeProvider(models));
+  pi.on("message_end", handleClineFreeError);
+}
+
+export {
+  MODELS,
+  modelIds,
+  fetchRemoteModels,
+  resolveModels,
+  isClineFreeGatewayModelId,
+} from "./models.js";
+export { PROVIDER_NAME, ENV_API_KEY, resolveApiBase } from "./env.js";
+export { resolveApiKey } from "./auth.js";
+export { createClineFreeProvider, loadModelCatalog } from "./provider.js";

package/src/models.ts

@@ -0,0 +1,234 @@
+import { isRecord, stringValue, numberValue, booleanValue } from "./utils.js";
+import { resolveApiBase } from "./env.js";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export type ThinkingLevelMap = Readonly<Record<ThinkingLevel, string | null>>;
+
+export const DEFAULT_THINKING_LEVEL_MAP: ThinkingLevelMap = {
+  off: "none",
+  minimal: null,
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: null,
+};
+
+export const NO_THINKING_MAP: ThinkingLevelMap = {
+  off: null,
+  minimal: null,
+  low: null,
+  medium: null,
+  high: null,
+  xhigh: null,
+};
+
+export const GLM_FLASH_THINKING_LEVEL_MAP: ThinkingLevelMap = {
+  off: null,
+  minimal: null,
+  low: "low",
+  medium: null,
+  high: "high",
+  xhigh: "max",
+};
+
+export interface ClineFreeOpenAICompat {
+  readonly supportsDeveloperRole: boolean;
+  readonly thinkingFormat?: "zai";
+  readonly zaiToolStream?: boolean;
+}
+
+export const CLINEFREE_OPENAI_COMPAT = {
+  supportsDeveloperRole: false,
+  thinkingFormat: "zai",
+  zaiToolStream: true,
+} as const satisfies ClineFreeOpenAICompat;
+
+export interface ModelConfig {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: readonly ["text"];
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  contextWindow: number;
+  maxTokens: number;
+  thinkingLevelMap: ThinkingLevelMap;
+  compat: ClineFreeOpenAICompat;
+}
+
+interface ModelConfigBase extends Omit<ModelConfig, "compat"> {
+  compat?: Partial<ClineFreeOpenAICompat>;
+}
+
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+const MODELS_BASE: readonly ModelConfigBase[] = [
+  {
+    id: "z-ai/glm-5.3-flash",
+    name: "GLM 5.3 Flash (Cline free)",
+    reasoning: true,
+    input: ["text"],
+    cost: ZERO_COST,
+    contextWindow: 1_048_576,
+    maxTokens: 131_072,
+    thinkingLevelMap: GLM_FLASH_THINKING_LEVEL_MAP,
+  },
+  {
+    id: "z-ai/glm-5.2:free",
+    name: "GLM 5.2 Free (Cline)",
+    reasoning: true,
+    input: ["text"],
+    cost: ZERO_COST,
+    contextWindow: 1_048_576,
+    maxTokens: 131_072,
+    thinkingLevelMap: DEFAULT_THINKING_LEVEL_MAP,
+  },
+  {
+    id: "z-ai/glm-4.7-flash",
+    name: "GLM 4.7 Flash (Cline)",
+    reasoning: true,
+    input: ["text"],
+    cost: ZERO_COST,
+    contextWindow: 1_048_576,
+    maxTokens: 131_072,
+    thinkingLevelMap: GLM_FLASH_THINKING_LEVEL_MAP,
+  },
+];
+
+export const MODELS: readonly ModelConfig[] = MODELS_BASE.map((model) => ({
+  ...model,
+  compat: {
+    ...CLINEFREE_OPENAI_COMPAT,
+    ...model.compat,
+  },
+}));
+
+export function modelIds(): string[] {
+  return MODELS.map((m) => m.id);
+}
+
+export const MODELS_ENDPOINT = "/api/v1/models";
+export const MODELS_FETCH_TIMEOUT_MS = 5_000;
+
+interface RawModelEntry {
+  id?: unknown;
+  name?: unknown;
+  context_length?: unknown;
+  max_output_tokens?: unknown;
+  pricing?: unknown;
+  reasoning?: unknown;
+}
+
+function toMicroPerToken(val: unknown, fallbackVal: number): number {
+  const n = numberValue(val);
+  return n != null ? n * 1_000_000 : fallbackVal;
+}
+
+function parseRemoteModel(raw: RawModelEntry, fallback?: ModelConfig): ModelConfig | undefined {
+  const id = stringValue(raw.id);
+  if (!id) return undefined;
+
+  const name = stringValue(raw.name) ?? fallback?.name ?? id;
+  const contextWindow = numberValue(raw.context_length) ?? fallback?.contextWindow ?? 128_000;
+  const maxTokens = numberValue(raw.max_output_tokens) ?? fallback?.maxTokens ?? 8_192;
+  const reasoning = booleanValue(raw.reasoning) ?? fallback?.reasoning ?? true;
+
+  const pricing = isRecord(raw.pricing) ? raw.pricing : undefined;
+  const cost = {
+    input: toMicroPerToken(pricing?.prompt, fallback?.cost.input ?? 0),
+    output: toMicroPerToken(pricing?.completion, fallback?.cost.output ?? 0),
+    cacheRead: toMicroPerToken(pricing?.cached_input, fallback?.cost.cacheRead ?? 0),
+    cacheWrite: fallback?.cost.cacheWrite ?? 0,
+  };
+
+  return {
+    id,
+    name,
+    reasoning,
+    input: ["text"],
+    cost,
+    contextWindow,
+    maxTokens,
+    thinkingLevelMap: reasoning
+      ? (fallback?.thinkingLevelMap ??
+          (id.includes("flash") ? GLM_FLASH_THINKING_LEVEL_MAP : DEFAULT_THINKING_LEVEL_MAP))
+      : NO_THINKING_MAP,
+    compat: {
+      ...CLINEFREE_OPENAI_COMPAT,
+      ...fallback?.compat,
+    },
+  };
+}
+
+export function isClineFreeGatewayModelId(id: string): boolean {
+  if (!id.startsWith("z-ai/")) return false;
+  if (id.startsWith("~")) return false;
+  if (id.endsWith(":batch")) return false;
+  return true;
+}
+
+export interface RemoteModelsOptions {
+  apiBase?: string;
+  apiKey?: string;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+}
+
+export async function fetchRemoteModels(
+  options: RemoteModelsOptions = {},
+): Promise<ModelConfig[] | undefined> {
+  const apiBase = options.apiBase ?? resolveApiBase();
+  const apiKey = options.apiKey;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? MODELS_FETCH_TIMEOUT_MS;
+
+  if (!apiKey || !fetchFn) return undefined;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchFn(`${apiBase}${MODELS_ENDPOINT}`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: controller.signal,
+    });
+
+    if (!response.ok) return undefined;
+
+    const json: unknown = await response.json();
+    const rawList: RawModelEntry[] = Array.isArray(json)
+      ? json
+      : isRecord(json) && Array.isArray(json.data)
+        ? (json.data as RawModelEntry[])
+        : [];
+
+    if (rawList.length === 0) return undefined;
+
+    const staticById = new Map(MODELS.map((m) => [m.id, m]));
+
+    const parsed = rawList.reduce<ModelConfig[]>((acc, raw) => {
+      const id = stringValue(raw?.id);
+      if (!id || !isClineFreeGatewayModelId(id)) return acc;
+      const model = parseRemoteModel(raw, staticById.get(id));
+      if (model) acc.push(model);
+      return acc;
+    }, []);
+
+    return parsed.length > 0 ? parsed : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function resolveModels(
+  apiKey?: string,
+  options: RemoteModelsOptions = {},
+): Promise<readonly ModelConfig[]> {
+  if (apiKey) {
+    const remote = await fetchRemoteModels({ ...options, apiKey });
+    if (remote) return remote;
+  }
+  return MODELS;
+}

package/src/oauth.ts

@@ -0,0 +1,84 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import { sanitizeApiKey } from "./env.js";
+import {
+  resolveClineAuthCredentials,
+  refreshWorkosToken,
+  credentialsFromWorkos,
+  WORKOS_REFRESH_MARGIN_MS,
+} from "./workos.js";
+
+const DASHBOARD_URL = "https://app.cline.bot/settings/api-keys";
+const TEN_YEARS_MS = 10 * 365 * 24 * 60 * 60 * 1000;
+
+function credentialsFromApiKey(apiKey: string): OAuthCredentials {
+  return {
+    refresh: apiKey,
+    access: apiKey,
+    expires: Date.now() + TEN_YEARS_MS,
+  };
+}
+
+async function loginWithManualApiKey(
+  callbacks: OAuthLoginCallbacks,
+  reason?: string,
+): Promise<OAuthCredentials> {
+  callbacks.onAuth({ url: DASHBOARD_URL });
+
+  const apiKey = sanitizeApiKey(
+    await callbacks.onPrompt({
+      message:
+        (reason ? `${reason} ` : "No Cline CLI login detected. ") +
+        "Paste your Cline API key " +
+        "(create one at the dashboard that just opened, under Settings → API Keys, " +
+        "or run `cline auth` first to reuse your Cline CLI login):",
+    }),
+  );
+
+  if (!apiKey) throw new Error("No Cline API key provided");
+
+  return credentialsFromApiKey(apiKey);
+}
+
+async function loginWithWorkosCredentials(
+  clineAuth: NonNullable<ReturnType<typeof resolveClineAuthCredentials>>,
+): Promise<OAuthCredentials> {
+  if (clineAuth.expiresAt <= Date.now() + WORKOS_REFRESH_MARGIN_MS) {
+    const tempCred = credentialsFromWorkos(
+      clineAuth.accessToken,
+      clineAuth.refreshToken,
+      clineAuth.expiresAt,
+    );
+    return refreshWorkosToken(tempCred);
+  }
+
+  return credentialsFromWorkos(clineAuth.accessToken, clineAuth.refreshToken, clineAuth.expiresAt);
+}
+
+export async function login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+  const clineAuth = resolveClineAuthCredentials();
+  if (clineAuth) {
+    try {
+      return await loginWithWorkosCredentials(clineAuth);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`[clinefree] WorkOS auto-login failed: ${message}`);
+      return loginWithManualApiKey(
+        callbacks,
+        "Cline login failed (refresh token may be expired or network is unreachable).",
+      );
+    }
+  }
+
+  return loginWithManualApiKey(callbacks);
+}
+
+export async function refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+  if (credentials.access.startsWith("workos:")) {
+    return refreshWorkosToken(credentials);
+  }
+  return credentialsFromApiKey(credentials.refresh);
+}
+
+export function getApiKey(credentials: OAuthCredentials): string {
+  return credentials.access;
+}

package/src/provider.ts

@@ -0,0 +1,103 @@
+import {
+  createProvider,
+  openAICompletionsApi,
+  type Model,
+  type Provider,
+} from "@earendil-works/pi-ai/compat";
+import type {
+  ApiKeyCredential,
+  OAuthCredential,
+  ProviderAuthInteraction,
+} from "@earendil-works/pi-ai";
+import { PROVIDER_NAME, ENV_API_KEY, resolveApiBase } from "./env.js";
+import { resolveModels, type ModelConfig } from "./models.js";
+import { login, refreshToken, getApiKey } from "./oauth.js";
+import {
+  interactionToOAuthCallbacks,
+  oauthCredentialToApiKey,
+  resolveAmbientAccessToken,
+} from "./runtime-auth.js";
+
+export const PROVIDER_ID = PROVIDER_NAME;
+
+function toPiModel(model: ModelConfig, baseUrl: string): Model<"openai-completions"> {
+  return {
+    id: model.id,
+    name: model.name,
+    api: "openai-completions",
+    provider: PROVIDER_ID,
+    baseUrl,
+    reasoning: model.reasoning,
+    thinkingLevelMap: { ...model.thinkingLevelMap },
+    input: [...model.input],
+    cost: { ...model.cost },
+    compat: { ...model.compat },
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
+  };
+}
+
+export function createClineFreeProvider(
+  models: readonly ModelConfig[],
+  env: NodeJS.ProcessEnv = process.env,
+): Provider<"openai-completions"> {
+  const apiBase = resolveApiBase(env);
+  const baseUrl = `${apiBase}/api/v1`;
+  const piModels = models.map((model) => toPiModel(model, baseUrl));
+
+  return createProvider({
+    id: PROVIDER_ID,
+    name: "Cline Free",
+    baseUrl,
+    auth: {
+      apiKey: {
+        name: "Cline API key",
+        async login(interaction: ProviderAuthInteraction): Promise<ApiKeyCredential> {
+          const credentials = await login(interactionToOAuthCallbacks(interaction));
+          return { type: "api_key", key: getApiKey(credentials) };
+        },
+        async resolve({ credential, signal }) {
+          const stored = credential ? oauthCredentialToApiKey(credential) : undefined;
+          if (stored) {
+            return { auth: { apiKey: stored }, source: "stored Cline credential" };
+          }
+
+          const ambient = await resolveAmbientAccessToken(signal);
+          if (!ambient) return undefined;
+          return { auth: { apiKey: ambient.token }, source: ambient.source };
+        },
+      },
+      oauth: {
+        name: "Cline Free",
+        loginLabel: "Sign in with Cline CLI or API key",
+        async login(interaction: ProviderAuthInteraction): Promise<OAuthCredential> {
+          const credentials = await login(interactionToOAuthCallbacks(interaction));
+          return { type: "oauth", ...credentials };
+        },
+        async refresh(credential: OAuthCredential, signal: AbortSignal): Promise<OAuthCredential> {
+          signal.throwIfAborted();
+          const refreshed = await refreshToken(credential);
+          return { type: "oauth", ...refreshed };
+        },
+        async toAuth(credential: OAuthCredential) {
+          return { apiKey: getApiKey(credential) };
+        },
+      },
+    },
+    models: piModels,
+    async fetchModels({ signal, credential }) {
+      signal.throwIfAborted();
+      const stored = credential ? oauthCredentialToApiKey(credential) : undefined;
+      const apiKey = stored ?? (await resolveAmbientAccessToken(signal))?.token;
+      const remote = await resolveModels(apiKey, { apiBase });
+      return remote.map((model) => toPiModel(model, baseUrl));
+    },
+    api: openAICompletionsApi(),
+  });
+}
+
+export async function loadModelCatalog(apiKey?: string): Promise<readonly ModelConfig[]> {
+  return resolveModels(apiKey, { apiBase: resolveApiBase() });
+}
+
+export { ENV_API_KEY };

package/src/runtime-auth.ts

@@ -0,0 +1,96 @@
+import type { ProviderAuthInteraction } from "@earendil-works/pi-ai";
+import type { OAuthLoginCallbacks } from "@earendil-works/pi-ai/oauth";
+import { resolveApiKey } from "./auth.js";
+import { ENV_API_KEY } from "./env.js";
+import {
+  resolveClineAuthCredentials,
+  refreshWorkosToken,
+  credentialsFromWorkos,
+  WORKOS_REFRESH_MARGIN_MS,
+  isWorkosToken,
+} from "./workos.js";
+
+export function interactionToOAuthCallbacks(
+  interaction: ProviderAuthInteraction,
+): OAuthLoginCallbacks {
+  return {
+    onAuth: (info) => {
+      interaction.notify({ type: "auth_url", url: info.url, instructions: info.instructions });
+    },
+    onDeviceCode: (info) => {
+      interaction.notify({
+        type: "device_code",
+        userCode: info.userCode,
+        verificationUri: info.verificationUri,
+        intervalSeconds: info.intervalSeconds,
+        expiresInSeconds: info.expiresInSeconds,
+      });
+    },
+    onPrompt: async (prompt) =>
+      interaction.prompt({
+        type: "secret",
+        message: prompt.message,
+        placeholder: prompt.placeholder,
+        signal: interaction.signal,
+      }),
+    onSelect: async (prompt) => {
+      const selected = await interaction.prompt({
+        type: "select",
+        message: prompt.message,
+        options: prompt.options.map((option) => ({
+          id: option.id,
+          label: option.label,
+        })),
+        signal: interaction.signal,
+      });
+      return selected;
+    },
+    onProgress: (message) => {
+      interaction.notify({ type: "progress", message });
+    },
+  };
+}
+
+export async function resolveAmbientAccessToken(
+  signal?: AbortSignal,
+): Promise<{ token: string; source: string } | undefined> {
+  signal?.throwIfAborted();
+
+  const envKey = process.env[ENV_API_KEY]?.trim();
+  if (envKey) return { token: envKey, source: "CLINE_API_KEY" };
+
+  const staticKey = resolveApiKey();
+  if (staticKey) return { token: staticKey, source: "Cline config" };
+
+  const clineAuth = resolveClineAuthCredentials();
+  if (!clineAuth) return undefined;
+
+  if (clineAuth.expiresAt <= Date.now() + WORKOS_REFRESH_MARGIN_MS) {
+    const refreshed = await refreshWorkosToken(
+      credentialsFromWorkos(
+        clineAuth.accessToken,
+        clineAuth.refreshToken,
+        clineAuth.expiresAt,
+      ),
+    );
+    return { token: refreshed.access, source: "Cline CLI OAuth" };
+  }
+
+  return { token: clineAuth.accessToken, source: "Cline CLI OAuth" };
+}
+
+export function oauthCredentialToApiKey(credential: {
+  access?: string;
+  refresh?: string;
+  type?: string;
+  key?: string;
+}): string | undefined {
+  if (typeof credential.key === "string" && credential.key.trim()) {
+    return credential.key.trim();
+  }
+  if (typeof credential.access === "string" && credential.access.trim()) {
+    const access = credential.access.trim();
+    if (isWorkosToken(access) || access.length >= 20) return access;
+  }
+  return undefined;
+}

package/src/utils.ts

@@ -0,0 +1,21 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+export function numberValue(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    if (value.trim() === "") return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+  }
+  return undefined;
+}
+
+export function booleanValue(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}

package/src/workos.ts

@@ -0,0 +1,176 @@
+import type { OAuthCredentials } from "@earendil-works/pi-ai";
+import { isRecord, stringValue } from "./utils.js";
+import { resolveApiBase, WORKOS_TOKEN_PREFIX } from "./env.js";
+import { walkAuthPaths, type AuthKeyOptions } from "./config-store.js";
+
+export { WORKOS_TOKEN_PREFIX };
+
+export const CLINE_REFRESH_ENDPOINT = "/api/v1/auth/refresh";
+export const WORKOS_TOKEN_LIFETIME_MS = 55 * 60 * 1000;
+export const WORKOS_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+export const WORKOS_REFRESH_TIMEOUT_MS = 15_000;
+
+export interface ClineAuthCredentials {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+export function isWorkosToken(token: string): boolean {
+  return token.startsWith(WORKOS_TOKEN_PREFIX);
+}
+
+export function credentialsFromWorkos(
+  accessToken: string,
+  refreshToken: string,
+  expiresAt: number,
+): OAuthCredentials {
+  return {
+    access: accessToken,
+    refresh: refreshToken,
+    expires: expiresAt,
+  };
+}
+
+export interface WorkosRefreshOptions {
+  fetch?: typeof globalThis.fetch;
+  apiBase?: string;
+}
+
+export async function refreshWorkosToken(
+  credentials: OAuthCredentials,
+  options: WorkosRefreshOptions = {},
+): Promise<OAuthCredentials> {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const apiBase = options.apiBase ?? resolveApiBase();
+
+  let response;
+  try {
+    response = await fetchFn(`${apiBase}${CLINE_REFRESH_ENDPOINT}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        granttype: "refresh_token",
+        refreshToken: credentials.refresh,
+      }),
+      signal: AbortSignal.timeout(WORKOS_REFRESH_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new Error(
+        "Cline token refresh timed out — check your network or try a static API key.",
+        { cause: err },
+      );
+    }
+    throw err;
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "unknown error");
+    throw new Error(
+      `Cline token refresh failed (${response.status}): ${text}` +
+        " — try running `cline auth` to re-login, or use a static API key.",
+    );
+  }
+
+  const data = (await response.json()) as {
+    data?: { accessToken?: string; refreshToken?: string };
+    accessToken?: string;
+    refreshToken?: string;
+  };
+
+  const tokens = data.data ?? data;
+  const newAccessToken = tokens.accessToken;
+  const newRefreshToken = tokens.refreshToken;
+
+  if (!newAccessToken || !newRefreshToken) {
+    throw new Error("Cline token refresh returned unexpected response format");
+  }
+
+  const prefixedToken = isWorkosToken(newAccessToken) ? newAccessToken : `workos:${newAccessToken}`;
+
+  return credentialsFromWorkos(
+    prefixedToken,
+    newRefreshToken,
+    Date.now() + WORKOS_TOKEN_LIFETIME_MS - WORKOS_REFRESH_MARGIN_MS,
+  );
+}
+
+function resolveExpiresAt(expiresField: unknown): number {
+  if (typeof expiresField === "number" && Number.isFinite(expiresField)) {
+    return expiresField;
+  }
+  return 0;
+}
+
+function extractWorkosAuthFromRecord(
+  auth: Record<string, unknown>,
+): ClineAuthCredentials | undefined {
+  const accessToken = stringValue(auth.accessToken);
+  const refreshToken = stringValue(auth.refreshToken);
+  if (!accessToken || !refreshToken || !isWorkosToken(accessToken)) return undefined;
+
+  return {
+    accessToken,
+    refreshToken,
+    expiresAt: resolveExpiresAt(auth.expiresAt),
+  };
+}
+
+function extractPiProviderAuth(parsed: Record<string, unknown>): ClineAuthCredentials | undefined {
+  for (const field of ["clinefree", "clinepass"] as const) {
+    const providerField = parsed[field];
+    if (!isRecord(providerField)) continue;
+
+    const accessToken = stringValue(providerField.access);
+    const refreshToken = stringValue(providerField.refresh);
+    if (!accessToken || !refreshToken || !isWorkosToken(accessToken)) continue;
+
+    return {
+      accessToken,
+      refreshToken,
+      expiresAt: resolveExpiresAt(providerField.expires),
+    };
+  }
+  return undefined;
+}
+
+function collectClineProviderAuths(parsed: Record<string, unknown>): ClineAuthCredentials[] {
+  const providers = isRecord(parsed.providers) ? parsed.providers : undefined;
+  if (!providers) return [];
+
+  const results: ClineAuthCredentials[] = [];
+  for (const key of ["cline-pass", "cline"]) {
+    const provider = isRecord(providers[key]) ? providers[key] : undefined;
+    if (!provider) continue;
+    const settings = isRecord(provider.settings) ? provider.settings : undefined;
+    if (!settings) continue;
+    const auth = isRecord(settings.auth) ? settings.auth : undefined;
+    if (!auth) continue;
+    const cred = extractWorkosAuthFromRecord(auth);
+    if (cred) results.push(cred);
+  }
+  return results;
+}
+
+function pickFreshestAuth(candidates: ClineAuthCredentials[]): ClineAuthCredentials | undefined {
+  if (candidates.length === 0) return undefined;
+  return candidates.reduce((best, current) =>
+    current.expiresAt > best.expiresAt ? current : best,
+  );
+}
+
+export function resolveClineAuthCredentials(
+  options: AuthKeyOptions = {},
+): ClineAuthCredentials | undefined {
+  const candidates: ClineAuthCredentials[] = [];
+
+  walkAuthPaths(options, (parsed) => {
+    const piAuth = extractPiProviderAuth(parsed);
+    if (piAuth) candidates.push(piAuth);
+    candidates.push(...collectClineProviderAuths(parsed));
+    return undefined;
+  });
+
+  return pickFreshestAuth(candidates);
+}

package/tests/auth.test.ts

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveApiKey } from "../src/auth.ts";
+
+describe("resolveApiKey", () => {
+  it("prefers provided key", () => {
+    assert.equal(resolveApiKey("provided"), "provided");
+  });
+
+  it("reads CLINE_API_KEY from env", () => {
+    assert.equal(
+      resolveApiKey(undefined, { env: { CLINE_API_KEY: "env-key" } }),
+      "env-key",
+    );
+  });
+
+  it("reads clinepass OAuth from pi auth.json", () => {
+    const key = resolveApiKey(undefined, {
+      authPaths: ["/virtual/auth.json"],
+      fileExists: (p) => p === "/virtual/auth.json",
+      readFile: () =>
+        JSON.stringify({
+          clinepass: {
+            type: "oauth",
+            access: "workos:token",
+            refresh: "refresh",
+          },
+        }),
+    });
+    assert.equal(key, undefined);
+  });
+
+  it("reads static API key from clinefree auth field", () => {
+    const key = resolveApiKey(undefined, {
+      authPaths: ["/virtual/auth.json"],
+      fileExists: (p) => p === "/virtual/auth.json",
+      readFile: () =>
+        JSON.stringify({
+          clinefree: "static-api-key-from-pi-login",
+        }),
+    });
+    assert.equal(key, "static-api-key-from-pi-login");
+  });
+
+  it("reads static API key from Cline CLI providers.json", () => {
+    const key = resolveApiKey(undefined, {
+      authPaths: ["/virtual/providers.json"],
+      fileExists: (p) => p === "/virtual/providers.json",
+      readFile: () =>
+        JSON.stringify({
+          providers: {
+            "cline-pass": {
+              settings: {
+                apiKey: "cli-static-key",
+              },
+            },
+          },
+        }),
+    });
+    assert.equal(key, "cli-static-key");
+  });
+});

package/tests/e2e/smoke.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+
+if ! command -v pi >/dev/null 2>&1; then
+  echo "skip: pi not installed"
+  exit 0
+fi
+
+pi --list-models clinefree 2>&1 | grep -q "z-ai/glm-5.3-flash"
+echo "smoke ok: clinefree provider lists glm-5.3-flash"

package/tests/models.test.ts

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  MODELS,
+  modelIds,
+  isClineFreeGatewayModelId,
+  fetchRemoteModels,
+  resolveModels,
+  GLM_FLASH_THINKING_LEVEL_MAP,
+} from "../src/models.ts";
+
+describe("modelIds", () => {
+  it("returns static fallback model IDs", () => {
+    const ids = modelIds();
+    assert.equal(ids.length, MODELS.length);
+    assert.ok(ids.includes("z-ai/glm-5.3-flash"));
+    assert.ok(ids.includes("z-ai/glm-5.2:free"));
+    assert.ok(ids.includes("z-ai/glm-4.7-flash"));
+  });
+
+  it("all static IDs are z-ai gateway models", () => {
+    for (const id of modelIds()) {
+      assert.ok(isClineFreeGatewayModelId(id));
+    }
+  });
+});
+
+describe("isClineFreeGatewayModelId", () => {
+  it("accepts z-ai models", () => {
+    assert.equal(isClineFreeGatewayModelId("z-ai/glm-5.3-flash"), true);
+    assert.equal(isClineFreeGatewayModelId("z-ai/glm-5.2:free"), true);
+  });
+
+  it("rejects batch and alias models", () => {
+    assert.equal(isClineFreeGatewayModelId("z-ai/glm-5.3-flash:batch"), false);
+    assert.equal(isClineFreeGatewayModelId("~z-ai/glm-latest"), false);
+    assert.equal(isClineFreeGatewayModelId("cline-pass/glm-5.3"), false);
+  });
+});
+
+describe("fetchRemoteModels", () => {
+  it("filters remote list to z-ai gateway models", async () => {
+    const fetch = async () =>
+      ({
+        ok: true,
+        json: async () => ({
+          data: [
+            { id: "z-ai/glm-5.3-flash", name: "GLM 5.3 Flash" },
+            { id: "z-ai/glm-5.3-flash:batch", name: "batch" },
+            { id: "~z-ai/glm-latest", name: "alias" },
+            { id: "cline-pass/glm-5.3", name: "paid" },
+          ],
+        }),
+      }) as Response;
+
+    const models = await fetchRemoteModels({ apiKey: "test-key", fetch });
+    assert.ok(models);
+    assert.equal(models.length, 1);
+    assert.equal(models[0]?.id, "z-ai/glm-5.3-flash");
+  });
+
+  it("returns undefined when fetch fails", async () => {
+    const fetch = async () => ({ ok: false }) as Response;
+    const models = await fetchRemoteModels({ apiKey: "test-key", fetch });
+    assert.equal(models, undefined);
+  });
+});
+
+describe("resolveModels", () => {
+  it("falls back to static catalog without an API key", async () => {
+    const models = await resolveModels(undefined);
+    assert.equal(models.length, MODELS.length);
+    assert.equal(models[0]?.id, "z-ai/glm-5.3-flash");
+  });
+
+  it("uses remote models when available", async () => {
+    const fetch = async () =>
+      ({
+        ok: true,
+        json: async () => ({
+          data: [{ id: "z-ai/glm-5.3-flash", name: "GLM 5.3 Flash" }],
+        }),
+      }) as Response;
+
+    const models = await resolveModels("test-key", { fetch });
+    assert.equal(models.length, 1);
+    assert.equal(models[0]?.thinkingLevelMap.low, GLM_FLASH_THINKING_LEVEL_MAP.low);
+  });
+});

package/tests/runtime-auth.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isClineFreeGatewayModelId } from "../src/models.ts";
+import { oauthCredentialToApiKey } from "../src/runtime-auth.ts";
+
+describe("oauthCredentialToApiKey", () => {
+  it("reads api_key credentials", () => {
+    assert.equal(oauthCredentialToApiKey({ type: "api_key", key: "abc" }), "abc");
+  });
+
+  it("reads oauth access tokens", () => {
+    assert.equal(
+      oauthCredentialToApiKey({ type: "oauth", access: "workos:token", refresh: "r" }),
+      "workos:token",
+    );
+  });
+});
+
+describe("gateway model filter", () => {
+  it("includes glm-5.3-flash", () => {
+    assert.equal(isClineFreeGatewayModelId("z-ai/glm-5.3-flash"), true);
+  });
+});