pi-clinepass 0.1.0

package/src/errors.ts

@@ -0,0 +1,112 @@
+/**
+ * ClinePass error classification — maps provider error text to friendly,
+ * actionable messages surfaced through pi's UI.
+ *
+ * Classification order matters: the free-model route returns plain
+ * `403 Forbidden` when its Cline-CLI header gate rejects us, which must not
+ * be reported as a subscription problem, and free-limit errors may arrive
+ * wrapped in a generic 403/429 shell.
+ */
+
+import { isFreeDeepSeekModel } from "./headers.js";
+
+export type ClinePassErrorType =
+  | "not_subscribed"
+  | "auth_expired"
+  | "rate_limited"
+  | "free_limit_reached"
+  | "free_route_forbidden"
+  | "unknown";
+
+function matchesAny(text: string, patterns: string[]): boolean {
+  return patterns.some((p) => text.includes(p));
+}
+
+export const CLINEPASS_ERROR_MESSAGES: Record<ClinePassErrorType, string> = {
+  not_subscribed:
+    "ClinePass subscription required — or the organization account cannot use ClinePass. " +
+    "Visit app.cline.bot to subscribe / switch to your personal account, or run `pi /login`.",
+  auth_expired:
+    "ClinePass authentication expired. Run `pi /login` and select ClinePass to refresh credentials.",
+  rate_limited:
+    "ClinePass rate limit reached. Wait a moment and try again, or check your plan at app.cline.bot.",
+  free_limit_reached:
+    "Free model rate limit reached. Please wait a few moments and try again.",
+  free_route_forbidden:
+    "Free model route unavailable (HTTP 403). The free DeepSeek route is gated to Cline product " +
+    "surfaces — retry in a moment, or switch to a ClinePass model.",
+  unknown: "ClinePass request failed. Check your subscription at app.cline.bot or run `pi /login`.",
+};
+
+/**
+ * Classify a provider error string. `modelId` (the model of the failed
+ * request, e.g. "deepseek/deepseek-v4-flash") disambiguates 403s on the
+ * free route from subscription problems.
+ */
+export function classifyClinePassError(
+  errorMessage: string,
+  modelId?: string,
+): {
+  type: ClinePassErrorType;
+  message: string;
+} {
+  const lower = errorMessage.toLowerCase();
+
+  if (matchesAny(lower, ["401", "unauthorized", "invalid api key", "invalid_api_key"])) {
+    return { type: "auth_expired", message: CLINEPASS_ERROR_MESSAGES.auth_expired };
+  }
+  if (matchesAny(lower, ["429", "rate limit", "too many requests", "rate_limit"])) {
+    return { type: "rate_limited", message: CLINEPASS_ERROR_MESSAGES.rate_limited };
+  }
+  if (matchesAny(lower, ["free limit reached", "free limit", "try again in"])) {
+    return { type: "free_limit_reached", message: CLINEPASS_ERROR_MESSAGES.free_limit_reached };
+  }
+  if (
+    matchesAny(lower, [
+      "403",
+      "forbidden",
+      "subscription required",
+      "not subscribed",
+      "organization accounts cannot use",
+    ])
+  ) {
+    if (modelId && isFreeDeepSeekModel(modelId)) {
+      return { type: "free_route_forbidden", message: CLINEPASS_ERROR_MESSAGES.free_route_forbidden };
+    }
+    return { type: "not_subscribed", message: CLINEPASS_ERROR_MESSAGES.not_subscribed };
+  }
+  return { type: "unknown", message: CLINEPASS_ERROR_MESSAGES.unknown };
+}
+
+export interface ErrorContext {
+  hasUI: boolean;
+  ui: {
+    notify: (msg: string, type: "info" | "warning" | "error") => void;
+  };
+  model?: { provider?: string };
+}
+
+/** Handle a message_end event: classify ClinePass errors and notify. */
+export function handleClinePassError(
+  event: { message: unknown },
+  ctx: ErrorContext,
+): void {
+  if (!event.message) return;
+  const msg = event.message as {
+    stopReason?: string;
+    errorMessage?: string;
+    provider?: string;
+    model?: string;
+  };
+  if (msg.stopReason !== "error" || !msg.errorMessage) return;
+
+  const provider = msg.provider ?? ctx.model?.provider;
+  if (provider !== "clinepass" && provider !== "cline-pass") return;
+
+  const { message: friendly } = classifyClinePassError(msg.errorMessage, msg.model);
+  if (ctx.hasUI) {
+    ctx.ui.notify(friendly, "error");
+  } else {
+    console.error(`[pi-clinepass] ${friendly}`);
+  }
+}

package/src/headers.ts

@@ -0,0 +1,80 @@
+/**
+ * Free-model request headers.
+ *
+ * The gateway gates the free `deepseek/deepseek-v4-flash` route behind
+ * "Cline product surfaces" (HTTP 403 without them). We identify as the
+ * Cline CLI with a current version fetched from the npm registry, cached
+ * for 24h with a bundled fallback. Only the free deepseek model is affected.
+ */
+
+import { release } from "node:os";
+
+export const FREE_DEEPSEEK_MODEL = "deepseek/deepseek-v4-flash";
+const FALLBACK_CLINE_VERSION = "3.0.54";
+const VERSION_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/cline/latest";
+
+let cachedVersion: string | undefined;
+let cachedAt = 0;
+let inflightVersion: Promise<string> | undefined;
+
+export async function getClineVersion(
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<string> {
+  if (cachedVersion && Date.now() - cachedAt < VERSION_CACHE_TTL_MS) return cachedVersion;
+  // Deduplicate concurrent callers (e.g. session_start + a command racing).
+  if (inflightVersion) return inflightVersion;
+  inflightVersion = (async () => {
+    try {
+      const res = await fetchFn(NPM_REGISTRY_URL);
+      if (res.ok) {
+        const data = (await res.json()) as { version?: unknown };
+        if (typeof data.version === "string" && data.version) {
+          cachedVersion = data.version;
+          cachedAt = Date.now();
+          return cachedVersion;
+        }
+      }
+    } catch {
+      // fall through to bundled default
+    }
+    // Registry unreachable: use the bundled fallback but do not cache it
+    // for the full TTL — the next session retries so a transient outage
+    // doesn't pin an outdated version for a day.
+    cachedVersion = FALLBACK_CLINE_VERSION;
+    cachedAt = 0;
+    return cachedVersion;
+  })();
+  try {
+    return await inflightVersion;
+  } finally {
+    inflightVersion = undefined;
+  }
+}
+
+export function isFreeDeepSeekModel(modelId: string): boolean {
+  return modelId.includes(FREE_DEEPSEEK_MODEL) && !modelId.includes("cline-pass/");
+}
+
+/** Whether the given model id needs the Cline-CLI identifying headers. */
+export function needsFreeModelHeaders(modelId: string): boolean {
+  return isFreeDeepSeekModel(modelId);
+}
+
+/**
+ * Build the headers that make the free deepseek route servable.
+ * Synchronous: uses the cached version (pre-warmed at startup or from a
+ * previous request), falling back to the bundled default. Never fetches
+ * inside a request path.
+ */
+export function buildFreeModelHeadersSync(): Record<string, string> {
+  const version = cachedVersion ?? FALLBACK_CLINE_VERSION;
+  return {
+    "x-client-type": "cli",
+    "x-client-version": version,
+    "x-core-version": version,
+    "x-platform": process.platform,
+    "x-platform-version": release(),
+    "user-agent": `Cline/${version}`,
+  };
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * pi-clinepass — ClinePass provider for pi.
+ *
+ * Registers the `clinepass` provider (13 paid models with measured billing
+ * prices + 3 free models) and wires the hooks that keep pi's numbers real:
+ *   - message_end → server-truth cost meter + session total + error surface
+ *   - before_provider_headers → free deepseek route headers
+ *   - model_select / session_start → immediate meter + default model sync
+ *   - /clinepass → price table + plan limit report
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { MODELS } from "./catalog.js";
+import { DEFAULT_API_BASE, WORKOS_TOKEN_PREFIX } from "./workos.js";
+import { getApiKey, login, refreshToken } from "./auth.js";
+import {
+  getCapReport,
+  handleInitialMeter,
+  handleUsageTracking,
+  PROVIDER_NAME,
+} from "./usage.js";
+import { buildFreeModelHeadersSync, getClineVersion, needsFreeModelHeaders } from "./headers.js";
+import { handleClinePassError } from "./errors.js";
+import { savePiDefaultModel } from "./settings.js";
+
+export default async function (pi: ExtensionAPI) {
+  pi.registerProvider(PROVIDER_NAME, {
+    name: "ClinePass",
+    baseUrl: `${DEFAULT_API_BASE}/api/v1`,
+    authHeader: true,
+    // ClinePass is OpenAI-compatible; pi's built-in openai-completions
+    // streaming handles SSE, tools, and usage. No custom streamSimple.
+    api: "openai-completions",
+    oauth: {
+      name: "ClinePass",
+      isSubscription: true,
+      login,
+      refreshToken,
+      getApiKey,
+    },
+    models: MODELS.map((model) => ({
+      ...model,
+      input: [...model.input],
+    })),
+  });
+
+  // Persist the per-turn server bill as a custom session entry so the
+  // session total survives resume/fork, then surface it in the status meter.
+  const writeCostEntry = (usage: { id: string; costUsd: number; model: string }): void => {
+    pi.appendEntry("clinepass-cost", {
+      usageId: usage.id,
+      costUsd: usage.costUsd,
+      model: usage.model,
+    });
+  };
+
+  pi.on("message_end", (event, ctx) => {
+    handleClinePassError(event, ctx);
+    // Billing tracking is queued in the background: message_end handlers
+    // are awaited inline by pi and gate message finalization + the agent
+    // loop, so polling the usage API (with its server flush delay) must
+    // never run on this path.
+    void handleUsageTracking(event, ctx, writeCostEntry);
+  });
+
+  // The free deepseek route requires Cline-CLI identifying headers. The
+  // version is pre-warmed at session_start (the factory must stay
+  // network-free) so the sync handler never fetches.
+  pi.on("before_provider_headers", (event, ctx) => {
+    const modelId = ctx.model?.id ?? "";
+    if (!needsFreeModelHeaders(modelId)) return;
+    Object.assign(event.headers, buildFreeModelHeadersSync());
+  });
+
+  pi.on("model_select", (event, ctx) => {
+    const { provider, id } = event.model;
+    const modelId = id.startsWith(`${provider}/`) ? id.slice(provider.length + 1) : id;
+    // Persist the global default only for explicit selections of our models:
+    // model cycling (Ctrl+P) and old-session restores must not rewrite the
+    // user's global default, and other providers manage their own settings.
+    if (event.source === "set" && (provider === PROVIDER_NAME || provider === "cline-pass")) {
+      void savePiDefaultModel(provider, modelId);
+    }
+    void handleInitialMeter(ctx);
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    // Pre-warm the Cline CLI version here instead of the factory: the
+    // factory runs for every invocation (including --list-models). The
+    // sync header builder falls back to the bundled version until this
+    // fetch completes.
+    void getClineVersion().catch(() => {});
+    void handleInitialMeter(ctx);
+  });
+
+  pi.registerCommand("clinepass", {
+    description: "Show ClinePass model rates and plan limit utilization",
+    handler: async (_args, ctx) => {
+      const report = await getCapReport();
+      if (ctx.hasUI && ctx.ui.notify) {
+        ctx.ui.notify(report, "info");
+      } else {
+        console.log(`\n${report}\n`);
+      }
+    },
+  });
+}
+
+export { MODELS, PROVIDER_NAME, WORKOS_TOKEN_PREFIX };

package/src/settings.ts

@@ -0,0 +1,49 @@
+/**
+ * Persist the selected model as pi's global default (settings.json).
+ *
+ * pi keeps model selection session-scoped; syncing it here means new
+ * sessions start with the model actually used. Best-effort: never throws.
+ */
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const PI_SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+
+export async function savePiDefaultModel(provider: string, modelId: string): Promise<void> {
+  try {
+    if (!existsSync(PI_SETTINGS_PATH)) return;
+    // pi's settings-manager holds `<path>.lock` while writing; wait briefly
+    // (without blocking the event loop) so we don't interleave with its
+    // read-modify-write cycle.
+    for (let attempt = 0; attempt < 5 && existsSync(`${PI_SETTINGS_PATH}.lock`); attempt++) {
+      await sleep(100);
+    }
+    const settings = JSON.parse(readFileSync(PI_SETTINGS_PATH, "utf8")) as Record<string, unknown>;
+    if (settings.defaultProvider === provider && settings.defaultModel === modelId) return;
+    settings.defaultProvider = provider;
+    settings.defaultModel = modelId;
+    atomicWrite(PI_SETTINGS_PATH, JSON.stringify(settings, null, 2));
+  } catch (err) {
+    console.warn(
+      `[pi-clinepass] failed to save default model: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function atomicWrite(filePath: string, data: string): void {
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, data, "utf8");
+  // rename replaces atomically on POSIX; on Windows it may fail if the
+  // target is open — fall back to direct write in that case.
+  try {
+    renameSync(tmp, filePath);
+  } catch {
+    writeFileSync(filePath, data, "utf8");
+  }
+}