pi-umans-provider 1.0.34 → 1.0.36

package/AGENTS.md

@@ -19,6 +19,7 @@ When a model needs overrides, new properties, or corrections, edit the appropria
 | `patch.json` | Per-model overrides keyed by model ID. Add reasoning flags, compat settings, pricing corrections, thinking level maps, etc. Applied on top of `models.json` at runtime and for README generation. |
 | `custom-models.json` | Models that don't exist in the provider API (hidden models, router endpoints, cross-provider aliases). Merged after patch. Format: array of full model objects (same schema as `models.json` entries). |
 | `index.ts` | Provider extension code. |
+| `sync-policy.ts` | Quiet startup sync policy (TTL, key fingerprint, cross-process lock). Provider-agnostic and shared verbatim across pi-*-provider repos — keep it free of provider specifics. |
 | `scripts/update-models.js` | The sync script itself (edit only if changing how models are fetched/transformed). |
 
 ## Data Flow

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.36
+
+- `/login` while the session-start catalog revalidation is still in flight now fetches the new key's catalog right away: the forced refresh aborts the old-key revalidation and waits for it to release the sync lock instead of skipping as "locked" until the next session start.
+
+## 1.0.35
+
+- Quiet startup sync: background `/v1/models/info` revalidation runs only with an API key, only when the disk cache is older than 1 hour (`PI_PROVIDER_SYNC_TTL_MS`, `0` = always), missing, or fetched with a different key, and only in one pi process at a time (lock file next to the cache). Failed refreshes back off for 5 minutes; sessions that skip adopt a cache refreshed by another process. `/login` forces a revalidation with the new key.
+- Never store the API key: key changes are detected via a salted sha256 fingerprint in `cache/umans-models.sync.json`. The cache file format is unchanged.
+- Usage footer: `/v1/usage` is no longer called without a UI (print mode, headless child agents). The session-start usage fetch is shared across pi processes for 60 seconds via `cache/umans-usage.json`; turn-end and idle polling are unchanged.
+- Write the model cache atomically and swallow API key resolution failures in `session_start`.
+- Add vitest coverage for the sync policy and the session_start integration.
+
 ## 1.0.32
 
 - Validate provider registration and session lifecycle against Pi 1.0.0; update the pinned development SDK.

package/README.md

@@ -22,6 +22,7 @@ _A [pi](https://github.com/earendil-works/pi-coding-agent) provider extension wi
 - **Streaming** - Real-time token streaming
 - **Subscription-based** - All models included in your plan, no per-token cost
 - **Usage status bar** — Displays your plan, concurrent sessions, and remaining requests in the pi footer
+- **Quiet live model sync** — Models refresh from the UMANS API in the background, at most hourly and by one pi process at a time ([details](#model-sync))
 
 ## Available Models
 
@@ -105,6 +106,7 @@ Get your API key from [code.umans.ai](https://code.umans.ai).
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `UMANS_API_KEY` | No | Your UMANS API key (fallback if not in auth.json) |
+| `PI_PROVIDER_SYNC_TTL_MS` | No | Model sync freshness window in ms (default `3600000`; `0` = revalidate every session start) |
 
 ## Configuration
 
@@ -158,6 +160,23 @@ Code Max (Founding Seat) | ⟠ 1/4
 
 The concurrent-session count is tracked locally: it's optimistically incremented the moment an agent run starts (no API call needed — the server has a brief registration lag anyway), reconciled with UMANS's `/v1/usage` endpoint after each agent run ends, and lightly polled while idle so the baseline stays fresh. The plan name and request budget are fetched on session start and model selection.
 
+The footer (and every `/v1/usage` call) is interactive-only: print mode (`pi -p`) and headless child agents never poll. On session start, one pi process per 60 seconds calls `/v1/usage` and writes the result to `~/.pi/agent/cache/umans-usage.json` (with the same lock and key fingerprint as the model sync); other sessions started within that window render it from disk.
+
+## Model sync
+
+Startup never waits on the network. pi starts with the cached catalog (`~/.pi/agent/cache/umans-models.json`,
+falling back to the bundled `models.json`) and revalidates against `/v1/models/info` in the background — only when:
+
+- a UMANS API key is configured (no key, no request),
+- the cache is older than 1 hour, missing, or was fetched with a different API key, and
+- no other pi process is already refreshing it (an `umans-models.lock` file next to the cache).
+
+So `/new`, `/reload`, `pi -p` and fan-out child agents share one cache instead of each calling the API; a
+session that skips the fetch still picks up a cache another process refreshed. Logging in with `/login` revalidates
+right away. A failed refresh is retried after 5 minutes at the earliest. `PI_PROVIDER_SYNC_TTL_MS` changes the
+window (`0` revalidates on every session start). Only a hash fingerprint of the key is stored
+(`umans-models.sync.json`), never the key itself.
+
 ## API Compatibility
 
 The UMANS API follows OpenAI conventions with these differences (handled via `patch.json` and `before_provider_request` hook):

package/index.ts

@@ -19,6 +19,10 @@
  * Model resolution strategy: Stale-While-Revalidate
  *   1. Serve stale immediately: disk cache → embedded models.json (zero-latency)
  *   2. Revalidate in background: live API /v1/models/info → merge with embedded → cache → hot-swap
+ *      Quiet startup sync (sync-policy.ts): only with an API key, only when the
+ *      disk cache is older than the TTL (1h, PI_PROVIDER_SYNC_TTL_MS) or the key
+ *      changed, and only one pi process at a time (lock file next to the cache).
+ *      /login forces a revalidation with the new key.
  *   3. patch.json + custom-models.json applied on top of whichever source won
  *
  * Merge order: [live|cache|embedded] → apply patch.json → merge custom-models.json
@@ -45,6 +49,14 @@ import patchData from "./patch.json" with { type: "json" };
 import deprecatedData from "./deprecated-models.json" with { type: "json" };
 import fs from "fs";
 import path from "path";
+import {
+  acquireModelSync,
+  cacheChangedSinceLoad,
+  keyFingerprint,
+  markCacheLoaded,
+  syncMetaPath,
+  writeFileAtomic,
+} from "./sync-policy";
 
 // ─── Usage/Plan Types ────────────────────────────────────────────────────────
 
@@ -53,6 +65,15 @@ const USAGE_FETCH_TIMEOUT_MS = 5000;
 const USAGE_THROTTLE_MS = 30_000;
 const END_SETTLE_MS = 2000;
 const IDLE_POLL_MS = 45_000;
+/**
+ * Startup usage dedupe window. Every interactive session_start used to call
+ * /v1/usage; now one process per window fetches and writes the result to
+ * `cache/umans-usage.json`, and sessions started inside the window (/new,
+ * /reload, a second terminal) render it from disk. 60s: the plan name and
+ * request budget barely move, and the concurrent-session baseline is refreshed
+ * by the idle poll (IDLE_POLL_MS) and after every agent run anyway.
+ */
+const USAGE_SYNC_TTL_MS = 60_000;
 
 let sessionPlan: string | null = null;
 let sessionConcurrency: number | null = null;
@@ -287,7 +308,8 @@ function loadCachedModels(): JsonModel[] | null {
 function cacheModels(models: JsonModel[]): void {
   try {
     fs.mkdirSync(CACHE_DIR, { recursive: true });
-    fs.writeFileSync(CACHE_PATH, JSON.stringify(models, null, 2) + "\n");
+    // Atomic (tmp + rename): other pi processes may be reading the cache right now.
+    writeFileAtomic(CACHE_PATH, JSON.stringify(models, null, 2) + "\n");
   } catch {
     // Cache write failure is non-fatal
   }
@@ -359,6 +381,7 @@ function withDeprecated(models: JsonModel[]): JsonModel[] {
 }
 
 function loadStaleModels(embeddedModels: JsonModel[]): JsonModel[] {
+  markCacheLoaded(CACHE_PATH); // stat before read: lets session_start spot newer caches
   const cached = loadCachedModels();
   if (!cached || cached.length === 0) return embeddedModels;
 
@@ -371,23 +394,43 @@ function loadStaleModels(embeddedModels: JsonModel[]): JsonModel[] {
   return cached;
 }
 
+/**
+ * Background revalidation, gated by the quiet startup sync policy
+ * (sync-policy.ts): no key → no fetch; fresh cache (TTL) → no fetch; another
+ * process already fetching → no fetch. When skipped, a cache that another
+ * process refreshed since we loaded it is adopted from disk instead.
+ * `force` bypasses the TTL (e.g. after /login); it is still single-flight.
+ *
+ * The Umans "OAuth" credential is the API key itself (access === refresh, never
+ * rotated), so it doubles as the stable identity for the key fingerprint.
+ */
 async function revalidateModels(
   apiKey: string | undefined,
   embeddedModels: JsonModel[],
   signal?: AbortSignal,
+  force = false,
 ): Promise<JsonModel[] | null> {
-  if (!apiKey) return null;
-  const liveModels = await fetchLiveModels(apiKey, signal);
-  if (!liveModels || liveModels.length === 0) return null;
-  const merged = mergeWithEmbedded(liveModels, embeddedModels);
-  cacheModels(merged);
-  return merged;
+  const lease = acquireModelSync({ cachePath: CACHE_PATH, apiKey, force });
+  if (!lease) return cacheChangedSinceLoad(CACHE_PATH) ? loadStaleModels(embeddedModels) : null;
+  let merged: JsonModel[] | null = null;
+  try {
+    const liveModels = apiKey ? await fetchLiveModels(apiKey, signal) : null;
+    if (!liveModels || liveModels.length === 0) return null;
+    merged = mergeWithEmbedded(liveModels, embeddedModels);
+    cacheModels(merged);
+    return merged;
+  } finally {
+    lease.release(merged ? "fetched" : signal?.aborted ? "aborted" : "failed");
+  }
 }
 
 // ─── API Key Resolution ────────────────────────────────────────────────────────
 
 let cachedApiKey: string | undefined;
 let revalidateAbort: AbortController | null = null;
+// The in-flight catalog revalidation (session start or /login); it never rejects.
+let modelSync: Promise<void> = Promise.resolve();
+let modelSyncAbort: AbortController | null = null;
 // Aborted on session replacement/shutdown so in-flight usage fetches from
 // timers don't resolve against a stale ctx (the timer handle itself can't be
 // clearTimeout'd once the async callback has already fired).
@@ -445,6 +488,59 @@ async function fetchUsage(
   }
 }
 
+// ─── Shared usage snapshot (cross-process startup dedupe) ─────────────────────
+
+const USAGE_CACHE_PATH = path.join(CACHE_DIR, `${PROVIDER_ID}-usage.json`);
+
+/** Read the usage snapshot another process wrote — only if it was fetched with this key. */
+function readUsageCache(apiKey: string): UmansUsage | null {
+  try {
+    const meta = JSON.parse(fs.readFileSync(syncMetaPath(USAGE_CACHE_PATH), "utf8"));
+    if (meta?.keyFingerprint !== keyFingerprint(apiKey)) return null;
+    const data = JSON.parse(fs.readFileSync(USAGE_CACHE_PATH, "utf8")) as UmansUsage;
+    return data?.plan?.slug ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeUsageCache(usage: UmansUsage): void {
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileAtomic(USAGE_CACHE_PATH, JSON.stringify(usage) + "\n");
+  } catch {
+    // Non-fatal: other processes just fetch for themselves next time.
+  }
+}
+
+/**
+ * Usage for session_start: one pi process per USAGE_SYNC_TTL_MS window calls
+ * /v1/usage (same lease/lock/backoff policy as the model sync, own cache
+ * file); the others render the snapshot it wrote. Never fetches without a key.
+ * `fetched` is false when this process skipped the network.
+ */
+async function startupUsage(
+  apiKey: string | undefined,
+  signal: AbortSignal,
+): Promise<{ usage: UmansUsage | null; fetched: boolean }> {
+  if (!apiKey) return { usage: null, fetched: false };
+  const lease = acquireModelSync({
+    cachePath: USAGE_CACHE_PATH,
+    apiKey,
+    ttlMs: USAGE_SYNC_TTL_MS,
+    isValidCache: (data) => data != null,
+  });
+  if (!lease) return { usage: readUsageCache(apiKey), fetched: false };
+  let usage: UmansUsage | null = null;
+  try {
+    usage = await throttledFetchUsage(apiKey, { force: true, signal });
+    if (usage) writeUsageCache(usage);
+    return { usage, fetched: true };
+  } finally {
+    lease.release(usage ? "fetched" : signal.aborted ? "aborted" : "failed");
+  }
+}
+
 function applyUsage(usage: UmansUsage, ctx: any): void {
   sessionPlan = usage.plan.display_name;
   sessionConcurrency = usage.limits?.concurrency?.limit ?? null;
@@ -573,6 +669,45 @@ export default function (pi: ExtensionAPI) {
   const staleBase = loadStaleModels(embeddedModels);
   const staleModels = buildModels(staleBase, customModels, patches);
 
+  function registerFresh(freshBase: JsonModel[]): void {
+    pi.registerProvider("umans", {
+      baseUrl: BASE_URL,
+      apiKey: "$UMANS_API_KEY",
+      api: "openai-completions",
+      models: buildModels(freshBase, customModels, patches),
+    });
+  }
+
+  // The catalog sync's own abort scope inside the session's: a /login cancels
+  // an in-flight (old-key) sync without cancelling the session's usage fetch.
+  function supersedeModelSync(session: AbortSignal): AbortSignal {
+    modelSyncAbort?.abort();
+    modelSyncAbort = new AbortController();
+    return AbortSignal.any([session, modelSyncAbort.signal]);
+  }
+
+  // After /login: revalidate with the new key right away (forced past the TTL,
+  // still single-flight). Deferred so pi stores the credential first; never
+  // awaited, never throws into the login flow.
+  async function loginAndRevalidate(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+    const credentials = await loginUmans(callbacks);
+    setTimeout(() => {
+      const key = credentials.access;
+      cachedApiKey = key;
+      if (!revalidateAbort || revalidateAbort.signal.aborted) revalidateAbort = new AbortController();
+      // The new key supersedes an in-flight revalidation, which must release its
+      // sync lock first, or this forced refresh would skip as "locked".
+      const signal = supersedeModelSync(revalidateAbort.signal);
+      modelSync = modelSync
+        .then(() => (signal.aborted ? null : revalidateModels(key, embeddedModels, signal, true)))
+        .then((freshBase) => {
+          if (freshBase && !signal.aborted) registerFresh(freshBase);
+        })
+        .catch(() => { /* keep serving the current catalog */ });
+    }, 0);
+    return credentials;
+  }
+
   pi.registerProvider("umans", {
     baseUrl: BASE_URL,
     apiKey: "$UMANS_API_KEY",
@@ -580,7 +715,7 @@ export default function (pi: ExtensionAPI) {
     models: staleModels,
     oauth: {
       name: "Umans AI (API Key)",
-      login: loginUmans,
+      login: loginAndRevalidate,
       refreshToken: refreshUmansToken,
       getApiKey: getApiKey,
     },
@@ -644,6 +779,8 @@ export default function (pi: ExtensionAPI) {
     return p;
   });
 
+  // Fire-and-forget: never await network here — startup must not block on the
+  // provider API. Nothing is awaited and every rejection is swallowed.
   pi.on("session_start", async (_event, ctx) => {
     revalidateAbort?.abort();
     revalidateAbort = new AbortController();
@@ -652,32 +789,38 @@ export default function (pi: ExtensionAPI) {
     usageAbort?.abort();
     usageAbort = new AbortController();
     const signal = revalidateAbort.signal;
-    resolveApiKey(ctx.modelRegistry).then(async () => {
-      revalidateModels(cachedApiKey, embeddedModels, signal).then((freshBase) => {
-        if (freshBase && !signal.aborted) {
-          pi.registerProvider("umans", {
-            baseUrl: BASE_URL,
-            apiKey: "$UMANS_API_KEY",
-            api: "openai-completions",
-            models: buildModels(freshBase, customModels, patches),
-          });
+    const keyResolved = resolveApiKey(ctx.modelRegistry);
+
+    const syncSignal = supersedeModelSync(signal);
+    modelSync = keyResolved
+      .then(() => revalidateModels(cachedApiKey, embeddedModels, syncSignal))
+      .then((freshBase) => {
+        if (freshBase && !syncSignal.aborted) registerFresh(freshBase);
+      })
+      .catch(() => { /* keep serving the stale catalog */ });
+
+    // Usage footer: interactive sessions only (no footer in print mode or
+    // headless child agents, so no /v1/usage call there either).
+    void keyResolved
+      .then(async () => {
+        if (!isUmansModel(ctx)) {
+          clearUsageStatus(ctx);
+          return;
         }
-      });
-
-      if (!isUmansModel(ctx)) {
-        clearUsageStatus(ctx);
-        return;
-      }
-
-      const usage = await throttledFetchUsage(cachedApiKey, { force: true, signal });
-      if (usage && !signal.aborted) {
-        applyUsage(usage, ctx);
-      }
-    });
+        if (!ctx.hasUI) return;
+        const { usage, fetched } = await startupUsage(cachedApiKey, signal);
+        if (signal.aborted) return;
+        if (usage) applyUsage(usage, ctx);
+        // Skipped the network and nothing usable on disk yet (another process
+        // is fetching right now): let the idle poll fill the footer in.
+        else if (!fetched && cachedApiKey) resetIdleTimer(ctx);
+      })
+      .catch(() => { /* the footer stays empty */ });
   });
 
   pi.on("model_select", (event, ctx) => {
     if (event.model?.provider === "umans") {
+      if (!ctx.hasUI) return; // no footer to render without a UI
       throttledFetchUsage(cachedApiKey, { force: true }).then((usage) => {
         if (usage) {
           applyUsage(usage, ctx);
@@ -695,7 +838,7 @@ export default function (pi: ExtensionAPI) {
   // registration lag, so fetching now would undercount us anyway. One span
   // per prompt (agent_start → agent_settled), so no flicker between tool turns.
   pi.on("agent_start", async (_event, ctx) => {
-    if (!isUmansModel(ctx)) return;
+    if (!isUmansModel(ctx) || !ctx.hasUI) return;
     if (idleTimer) {
       clearTimeout(idleTimer);
       idleTimer = null;
@@ -707,7 +850,7 @@ export default function (pi: ExtensionAPI) {
   // Turn ended: drop our optimistic +1 and reconcile with the server after a
   // short settle so the server has dropped our session from its count.
   pi.on("agent_settled", async (_event, ctx) => {
-    if (!isUmansModel(ctx)) return;
+    if (!isUmansModel(ctx) || !ctx.hasUI) return;
     activeStreams = Math.max(0, activeStreams - 1);
     updateUsageStatus(ctx);
     scheduleEndFetch(ctx);

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "pi-umans-provider",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "description": "UMANS provider extension for pi - Access Kimi K2.6, GLM 5.1, Qwen 3.6, and coding-optimized models through the UMANS API",
   "type": "module",
   "main": "index.ts",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "tsc --noEmit && vitest run && node scripts/test-pi-compat.mjs",
+    "test": "vitest run",
+    "update-models": "node scripts/update-models.js",
+    "test:pi": "node scripts/test-pi-compat.mjs",
+    "typecheck": "tsc --noEmit"
+  },
   "keywords": [
     "pi",
     "extension",
@@ -31,18 +40,11 @@
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",
     "@types/node": "^25.9.2",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "4.1.7"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*"
-  },
-  "scripts": {
-    "clean": "echo 'nothing to clean'",
-    "build": "echo 'nothing to build'",
-    "check": "tsc --noEmit && node scripts/test-pi-compat.mjs",
-    "update-models": "node scripts/update-models.js",
-    "test:pi": "node scripts/test-pi-compat.mjs",
-    "typecheck": "tsc --noEmit"
   }
-}
+}