@juvio15/pi-cliproxyapi-provider 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,100 @@
+# pi CLIProxyAPI provider
+
+The pi CLIProxyAPI provider is an extension for the [pi](https://github.com/earendil-works/pi) coding agent that lets pi use every model on a [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) server. CLIProxyAPI is a local server that puts your Claude, Codex, Kimi, Grok, and other accounts behind one API key.
+
+The extension sends each model through the API that suits it. Claude and Kimi models use the Anthropic Messages API, so cache marks and Anthropic options reach the model. Every other model uses the OpenAI Responses API.
+
+## What you get
+
+- A model list that comes from your CLIProxyAPI server, with the context windows and reasoning levels the server reports, and prices from [models.dev](https://models.dev)
+- A `web_search` tool that runs searches through CLIProxyAPI and estimates what each search cost, when the server reports token usage
+- A footer that shows tokens per second, and account usage if you add a management key
+- Commands for Fast mode, pausing requests, and adding upstream accounts
+
+## Requirements
+
+- Node.js 22.19 or later
+- pi 0.82 or later
+- A running CLIProxyAPI server and an API key for it
+
+## Install
+
+Install the package with pi:
+
+```sh
+pi install npm:@juvio15/pi-cliproxyapi-provider
+```
+
+Then start pi and run `/login cliproxyapi`. Pi asks for the server address and the API key, and the extension checks them by loading the model list. If you leave the address empty, the extension uses `http://127.0.0.1:8317`, which is the CLIProxyAPI default.
+
+## Connect without logging in
+
+You can set the connection in environment variables instead, which is useful when you run pi in scripts or other programs that have no login screen:
+
+```sh
+export CLIPROXYAPI_BASE_URL=http://127.0.0.1:8317
+export CLIPROXYAPI_API_KEY=your-key
+```
+
+The extension looks for each value in the environment first, then in `~/.pi/agent/cliproxyapi.json`, and then in the `/login` credentials. The address can be the server root or any of its API paths, e.g., `http://host:8317/v1`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/login cliproxyapi` | Saves the server address and API key |
+| `/cliproxyapi-status` | Shows the connection, model count, prices, and settings |
+| `/cliproxyapi-refresh` | Loads the model list from the server again |
+| `/cliproxyapi-login <provider>` | Adds an upstream account to CLIProxyAPI, e.g., `claude` or `codex` |
+| `/cliproxyapi-reset [model-id]` | Clears CLIProxyAPI cooldowns for every account, or only for the accounts that serve one model |
+| `/fast` | Turns Fast mode on or off for models that support it |
+| `/pause` and `/continue` | Holds provider requests until you continue |
+| `/websearch-model [model-id\|auto]` | Picks the model that `web_search` uses |
+
+The extension caches the model list for 10 minutes. It hides models that the server no longer lists, and models whose accounts have hit their usage limits.
+
+## Settings file
+
+You can put settings in `~/.pi/agent/cliproxyapi.json`. Every field is optional:
+
+```json
+{
+  "baseUrl": "http://127.0.0.1:8317",
+  "apiKey": "your-key",
+  "managementKey": "your-management-key",
+  "fast": false,
+  "pause": false,
+  "searchModel": "<model-id>",
+  "thinkingDisplay": { "<model-id>": "summarized" },
+  "providerId": "cliproxyapi",
+  "providerName": "CLIProxyAPI"
+}
+```
+
+The fields work as follows:
+
+- `managementKey` is the CLIProxyAPI management key. It turns on the usage footer, `/cliproxyapi-login`, and `/cliproxyapi-reset`. You can also set it with the `CLIPROXY_MANAGEMENT_KEY` environment variable.
+- `thinkingDisplay` sets, per model, whether the model sends thought summaries. It applies to models that use the Anthropic Messages API with thinking turned on. The default is `omitted`, because Claude streams its answer only when summaries are off. Set a model to `summarized` to see its summaries.
+- `searchModel` sets the model for `web_search`. When it's empty, the extension picks one.
+- `providerId` is the provider ID that pi uses in model names, e.g., `cliproxyapi/<model-id>`, and in `/login`. If you change it, pi looks for the login under the new ID, so you need to log in again. `providerName` is the name pi shows. The environment variables `CLIPROXYAPI_PROVIDER_ID` and `CLIPROXYAPI_PROVIDER_NAME` do the same.
+
+## Use the model mapping outside pi
+
+The files in `src/core` don't import `pi-coding-agent`, and they don't read files or environment variables on their own. Programs built on `pi-ai` can import them to load the catalog, pick an API per model, and build a provider. The list of exported functions is at the top of `src/core/index.ts`.
+
+## Development
+
+Install the dependencies and run the checks:
+
+```sh
+npm install
+npm run typecheck
+npm run check
+npm test
+```
+
+The scripts in `test/e2e` call a live CLIProxyAPI server, and `npm test` doesn't run them. Run one by hand, e.g., `node test/e2e/catalog.ts`. They use `CLIPROXYAPI_BASE_URL` and `CLIPROXYAPI_API_KEY`, or your pi login if those aren't set.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juvio15/pi-cliproxyapi-provider",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "pi provider for CLIProxyAPI: per-family APIs, model catalog, costs, web search, usage footer",
   "keywords": [
     "cliproxyapi",

package/src/core/catalog.ts

@@ -368,6 +368,13 @@ export const fetchCatalog = async (
   return "models" in payload ? payload.models : payload.data;
 };
 
+/**
+ * Drops models the latest catalog no longer lists. mergeCatalog keeps them so
+ * a session that uses one still resolves, but nobody should pick one anew.
+ */
+export const withoutStale = <T extends object>(models: readonly T[]): T[] =>
+  models.filter((model) => !("stale" in model && model.stale === true));
+
 export const mergeCatalog = (
   previous: readonly CliproxyModel[],
   fresh: readonly CliproxyModel[],

package/src/core/index.ts

@@ -13,9 +13,10 @@
  * matchModelCost(modelId: string, catalog: CostCatalog, fast?: boolean): ModelCost
  * mapCatalog(entries: readonly CatalogModel[], options: MappingOptions): MappedCatalog
  * mergeCatalog(previous: readonly CliproxyModel[], fresh: readonly CliproxyModel[], options?: MergeOptions): CliproxyModel[]
+ * withoutStale<T extends object>(models: readonly T[]): T[]
  * wrapCliproxyStreams(streams: ProviderStreams, settings: PayloadSettings): ProviderStreams
  * createCliproxyProvider(options: CliproxyProviderOptions): Provider<CliproxyApi>
- * quotaResetFromError(message: string, now?: number): number | undefined
+ * quotaResetFromError(message: string, now?: number, fallbackAt?: number): number | undefined
  * startOAuth(options: StartOAuthOptions): Promise<OAuthStart>
  * submitOAuthCallback(options: SubmitOAuthCallbackOptions): Promise<OAuthStatus>
  * pollOAuthStatus(options: PollOAuthStatusOptions): Promise<OAuthStatus>
@@ -32,7 +33,12 @@ import {
 import { createProvider } from "@earendil-works/pi-ai/models";
 import type { Provider } from "@earendil-works/pi-ai/models";
 
-import { fetchCatalog, mapCatalog, mergeCatalog } from "./catalog.ts";
+import {
+  fetchCatalog,
+  mapCatalog,
+  mergeCatalog,
+  withoutStale,
+} from "./catalog.ts";
 import type { CliproxyApi, CliproxyModel, MappingOptions } from "./catalog.ts";
 import { resolveEndpoints } from "./connection.ts";
 import { fetchCosts } from "./costs.ts";
@@ -46,6 +52,7 @@ export {
   mapCatalog,
   mergeCatalog,
   selectModelApi,
+  withoutStale,
   type CatalogFetchOptions,
   type CatalogModel,
   type CliproxyApi,
@@ -180,6 +187,7 @@ export const createCliproxyProvider = (
         staleTtlMs: options.staleTtlMs,
       });
     },
+    filterModels: (models) => withoutStale(models),
     id,
     models: options.models ?? [],
     name: options.providerName ?? "CLIProxyAPI",

package/src/core/usage.ts

@@ -46,11 +46,11 @@ const SECOND_MS = 1000;
 const MINUTE_MS = 60 * SECOND_MS;
 const FULL_PERCENT = 100;
 
-/** Wait this long when a quota error names no reset time. */
+/** Wait this long when a quota error names no reset time and nothing else knows it. */
 export const QUOTA_FALLBACK_MS = 15 * MINUTE_MS;
 
 const QUOTA_ERROR =
-  /quota exhausted|subscription quota|usage[ _]limit|usage window|insufficient_quota|rate limit reached/iu;
+  /quota exhausted|subscription quota|usage[ _]limit|usage window|insufficient_quota|rate limit reached|exceed your account's rate limit/iu;
 
 const RESETS_AT_EPOCH = /"resets_at"\s*:\s*(?<seconds>\d{9,})/u;
 const RESETS_AT_ISO = /resets at (?<time>\d{4}-\d{2}-\d{2}T[\d:.]+Z)/iu;
@@ -77,11 +77,14 @@ const isoTime = (value: string | undefined): number | undefined => {
 
 /**
  * When an error message says an upstream account ran out of quota, returns the
- * epoch milliseconds when it resets. Undefined for every other error.
+ * epoch milliseconds when it resets. Undefined for every other error. A message
+ * that names no reset time resets at `fallbackAt`, such as the reset of the
+ * account's full usage window.
  */
 export const quotaResetFromError = (
   message: string,
-  now = Date.now()
+  now = Date.now(),
+  fallbackAt = now + QUOTA_FALLBACK_MS
 ): number | undefined => {
   if (!QUOTA_ERROR.test(message)) {
     return undefined;
@@ -99,8 +102,7 @@ export const quotaResetFromError = (
   ];
 
   return (
-    candidates.find((time) => time !== undefined && time > now) ??
-    now + QUOTA_FALLBACK_MS
+    candidates.find((time) => time !== undefined && time > now) ?? fallbackAt
   );
 };
 

package/src/extension/index.ts

@@ -4,7 +4,11 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 
-import { resolveConnectionSources, resolveEndpoints } from "../core/index.ts";
+import {
+  resolveConnectionSources,
+  resolveEndpoints,
+  withoutStale,
+} from "../core/index.ts";
 import type { CliproxyModel } from "../core/index.ts";
 import { completeFrom } from "./completions.ts";
 import {
@@ -140,7 +144,7 @@ const registerCatalogCommands = (
         const models = controller.getModels();
         const stale = models.filter((model) => model.stale).length;
         ctx.ui.notify(
-          `Refreshed ${models.length} CLIProxyAPI models${stale ? ` (${stale} retained from cache)` : ""}.`,
+          `Refreshed ${models.length - stale} CLIProxyAPI models${stale ? `. Hid ${stale} that CLIProxyAPI no longer lists` : ""}.`,
           "info"
         );
       } catch (error) {
@@ -229,7 +233,7 @@ export default async function cliproxyapiProvider(
     configured: connection !== null,
     connection: initialConnection,
     fast,
-    filterAvailable: (models) => tracker.filter(models),
+    filterAvailable: (models) => tracker.filter(withoutStale(models)),
     onModels: (models) => {
       latestModels = models;
 
@@ -370,8 +374,9 @@ export default async function cliproxyapiProvider(
   });
   registerWebSearch(pi, {
     agentDir,
-    getAvailableModels: () => tracker.filter(controller.getModels()),
-    getModels: controller.getModels,
+    getAvailableModels: () =>
+      tracker.filter(withoutStale(controller.getModels())),
+    getModels: () => withoutStale(controller.getModels()),
     getStandardCost: controller.getStandardCost,
     providerId,
   });

package/src/extension/usage.ts

@@ -8,6 +8,7 @@ import { Type } from "typebox";
 import type { Static } from "typebox";
 
 import {
+  QUOTA_FALLBACK_MS,
   fetchUsage,
   quotaResetFromError,
   resetCooldowns as resetServerCooldowns,
@@ -86,6 +87,11 @@ const formatTime = (time: number, now: number): string => {
 export class UsageTracker {
   private readonly filePath: string;
   private readonly options: UsageTrackerOptions;
+  /** Quota marks this tracker guessed, by model id, until a usage fetch names the real reset. */
+  private readonly guessedMarks = new Map<
+    string,
+    { recordedAt: number; until: number }
+  >();
 
   constructor(options: UsageTrackerOptions) {
     this.options = options;
@@ -226,14 +232,28 @@ export class UsageTracker {
    * reset. Like CLIProxyAPI, a quota error covers the whole account, so its
    * other models hide too. Claude is the exception: it also has per-model weekly
    * limits, and its account-wide windows come from the usage fetch instead.
+   *
+   * The mark is written at once, without a network call. When the message
+   * names no reset time, as Claude's account rate limit does, the mark is a
+   * guess: the reset of the account's full window in the snapshot on disk,
+   * else 15 minutes. The next usage fetch replaces the guess with the reset
+   * it reports, unless the mark changed in between, such as by a reset.
    */
   recordError(modelId: string, message: string): boolean {
-    const until = quotaResetFromError(message);
+    const now = Date.now();
+
+    const guess =
+      this.accountResets(this.read(), now).get(modelId) ??
+      now + QUOTA_FALLBACK_MS;
+
+    const until = quotaResetFromError(message, now, guess);
 
     if (until === undefined) {
       return false;
     }
 
+    const marked: string[] = [];
+
     this.write((file) => {
       const siblings = this.providers(file)
         .filter(
@@ -245,15 +265,32 @@ export class UsageTracker {
       const exhausted = { ...file.exhausted };
 
       for (const id of [modelId, ...siblings]) {
-        exhausted[id] = Math.max(exhausted[id] ?? 0, until);
+        if ((exhausted[id] ?? 0) < until) {
+          exhausted[id] = until;
+          marked.push(id);
+        }
       }
 
       return { ...file, exhausted };
     });
 
+    if (until === guess) {
+      for (const id of marked) {
+        this.guessedMarks.set(id, { recordedAt: now, until });
+      }
+    }
+
     return true;
   }
 
+  /**
+   * Each model whose accounts are all full, with the time the first comes
+   * back. Local quota marks don't count.
+   */
+  private accountResets(file: UsageFile, now: number): Map<string, number> {
+    return this.hiddenFrom({ ...file, exhausted: {} }, now);
+  }
+
   /**
    * Clears local quota marks from the shared exhausted map: one model, or
    * every model when no id is given. Returns the model ids that were cleared.
@@ -372,6 +409,8 @@ export class UsageTracker {
       return;
     }
 
+    const startedAt = Date.now();
+
     const providers = await fetchUsage({
       baseUrl: connection.baseUrl,
       fetch: this.options.fetchFn,
@@ -379,12 +418,36 @@ export class UsageTracker {
       signal,
     });
 
-    this.write((file) => ({
-      ...file,
-      baseUrl: connection.baseUrl,
-      fetchedAt: Date.now(),
-      providers,
-    }));
+    this.write((file) => {
+      const fetchedAt = Date.now();
+
+      const next: UsageFile = {
+        ...file,
+        baseUrl: connection.baseUrl,
+        fetchedAt,
+        providers,
+      };
+
+      const resets = this.accountResets(next, fetchedAt);
+      const exhausted = { ...next.exhausted };
+
+      // A fetch that started before a guess was made can't know its reset.
+      for (const [id, guessed] of this.guessedMarks) {
+        if (guessed.recordedAt > startedAt) {
+          continue;
+        }
+
+        this.guessedMarks.delete(id);
+        const reset = resets.get(id);
+
+        // A mark that changed since the guess, or was cleared, is not ours to move.
+        if (reset !== undefined && exhausted[id] === guessed.until) {
+          exhausted[id] = reset;
+        }
+      }
+
+      return { ...next, exhausted };
+    });
   }
 
   /** When the next hidden model comes back or the snapshot goes stale, whichever is first. */
@@ -522,28 +585,33 @@ export const registerUsage = (
     ctx.ui.setStatus(STATUS_KEY, tracker.footer(options.getCatalogIds()));
   };
 
-  const update = async (
-    ctx: ExtensionContext,
-    force: boolean
-  ): Promise<void> => {
+  /** Applies the usage file to pi without a network call. */
+  const syncNow = async (ctx: ExtensionContext): Promise<void> => {
     try {
-      await tracker.refresh(force);
+      await sync(ctx);
     } catch (error) {
       warn(
         ctx,
-        `CLIProxyAPI usage: ${error instanceof Error ? error.message : String(error)}`
+        `CLIProxyAPI model list: ${error instanceof Error ? error.message : String(error)}`
       );
     }
+  };
 
+  const update = async (
+    ctx: ExtensionContext,
+    force: boolean
+  ): Promise<void> => {
     try {
-      await sync(ctx);
+      await tracker.refresh(force);
     } catch (error) {
       warn(
         ctx,
-        `CLIProxyAPI model list: ${error instanceof Error ? error.message : String(error)}`
+        `CLIProxyAPI usage: ${error instanceof Error ? error.message : String(error)}`
       );
     }
 
+    await syncNow(ctx);
+
     if (!ctx.hasUI || !active) {
       return;
     }
@@ -570,15 +638,24 @@ export const registerUsage = (
       return;
     }
 
+    const quotaError =
+      message.stopReason === "error" &&
+      tracker.recordError(message.model, message.errorMessage ?? "");
+
     const changed =
-      message.stopReason === "error"
-        ? tracker.recordError(message.model, message.errorMessage ?? "")
-        : message.stopReason !== "aborted" &&
-          tracker.recordSuccess(message.model);
+      quotaError ||
+      (message.stopReason !== "error" &&
+        message.stopReason !== "aborted" &&
+        tracker.recordSuccess(message.model));
 
-    if (changed) {
-      await update(ctx, false);
+    if (!changed) {
+      return;
     }
+
+    // pi awaits this handler before it retries, so only the local change
+    // waits. The usage fetch runs after it and names a guessed reset.
+    await syncNow(ctx);
+    void update(ctx, quotaError);
   });
   pi.on("session_start", async (_event, ctx) => {
     active = ctx;