/** /quota: provider-owned quota buckets, shared widget and footer presentation. */ import type { ExtensionAPI, ExtensionContext, } from "@earendil-works/pi-coding-agent"; import { closeDebug, dbg, span } from "./src/debug.ts"; import { mergeHeaders } from "./src/observations.ts"; import { object } from "./src/parse.ts"; import { offerFooterSegment, removeFooterSegment, } from "./src/pi-ext-footer-segment.ts"; import { defineIntegerSetting, MAX_TIMER_MS, resolveSetting, type SettingDeclaration, } from "./src/pi-ext-settings.ts"; import { providers as adapters } from "./src/providers/index.ts"; import { isRouted, quotaProviderKey } from "./src/routing.ts"; import type { ProviderQuota, QuotaBucket } from "./src/types.ts"; import { quotaColor, quotaPlainLabel, quotaStatusLabel, segmentText, selectFooterBucket, widgetLines, } from "./src/ui.ts"; const STATUS_ID = "quota"; const DEFAULT_REFRESH_MS = 5 * 60000; const REFRESH_SETTING: SettingDeclaration = defineIntegerSetting({ key: "quota.refreshIntervalMs", label: "Quota refresh interval", description: "Milliseconds between quota refreshes.", env: "PI_QUOTA_REFRESH_INTERVAL_MS", default: DEFAULT_REFRESH_MS, range: { min: 10000, max: MAX_TIMER_MS }, }); /** Providers other extensions report using outside chat, e.g. MiniMax media or search. */ const ACTIVITY_EVENT = "quota:provider-activity"; const MAX_EXTRA_PROVIDERS = 4; export default function quotaExtension(pi: ExtensionAPI): void { let quotas: ProviderQuota[] = []; let lastAttemptAt = 0; let fetchPromise: { generation: number; key: string | undefined; promise: Promise; } | null = null; let widgetVisible = false; let refreshTimer: ReturnType | null = null; let refreshMs = DEFAULT_REFRESH_MS; let generation = 0; let revision = 0; let currentProviderKey: string | undefined; const cache = new Map(); const headerUpdates = new Map< string, Map >(); const footerIds = new Set(); // Session-scoped secondary providers; shown beside, never instead of, the active one. const extras = new Set(); const extraQuotas = new Map(); const extraFetches = new Map< string, { generation: number; promise: Promise } >(); // Bus events carry no context; reuse the latest one a lifecycle hook or command provided. let lastCtx: ExtensionContext | undefined; function activeKey(ctx: ExtensionContext): string | undefined { return quotaProviderKey(ctx.model, ctx.sessionManager.getBranch()); } function visible(ctx: ExtensionContext): ProviderQuota[] { const active = activeKey(ctx); const shown = quotas.filter((q) => !active || q.provider === active); for (const [key, quota] of extraQuotas) if (key !== active) shown.push(quota); return shown; } function clearFooter() { for (const id of footerIds) removeFooterSegment(pi, id); footerIds.clear(); } function updateFooter(ctx: ExtensionContext) { if (!ctx.hasUI) return; const active = activeKey(ctx) ?? null; // Routed selections name the virtual model; label which provider's quota is shown. const routed = isRouted(ctx.model); const shown = visible(ctx); if (ctx.mode !== "tui") { clearFooter(); ctx.ui.setStatus(STATUS_ID, quotaPlainLabel(shown)); return; } let offered = false; let accepted = true; const seen = new Set(); for (const quota of shown) { const bucket = selectFooterBucket(quota); if (!bucket) continue; const [text, ...variants] = segmentText( quota, quota.provider === active && !routed, ); const id = `quota:${quota.provider}`; seen.add(id); footerIds.add(id); offered = true; accepted = offerFooterSegment(pi, { id, icon: "●", text, variants, color: quotaColor(bucket), zone: "llm", order: 4, }) && accepted; } for (const id of [...footerIds]) { if (seen.has(id)) continue; offered = true; accepted = removeFooterSegment(pi, id) && accepted; footerIds.delete(id); } accepted = offered && accepted; if (!accepted) clearFooter(); ctx.ui.setStatus(STATUS_ID, accepted ? undefined : quotaStatusLabel(shown)); } function updateWidget(ctx: ExtensionContext) { if (widgetVisible) ctx.ui.setWidget("usage", widgetLines(visible(ctx), ctx.ui.theme)); } async function credentialFor( ctx: ExtensionContext, key: string, ): Promise { if (key !== "minimax") return ctx.modelRegistry.getApiKeyForProvider(key); const auth = await ctx.modelRegistry.getProviderAuth(key); for (const baseUrl of [ ctx.modelRegistry.getProvider(key)?.baseUrl, auth?.auth.baseUrl, ]) { if (baseUrl && new URL(baseUrl).origin !== "https://api.minimax.io") throw new Error( "MiniMax M Plan quota credential region mismatch; no fallback.", ); } return auth?.auth.apiKey; } /** Poll one provider; falls back to its cached result when the poll fails. */ async function loadQuota( ctx: ExtensionContext, key: string | undefined, canPublish: () => boolean, ) { const fetchRevision = revision; let usage: ProviderQuota | undefined; let outcome: "success" | "cached" | "unavailable" = "unavailable"; try { const adapter = key ? adapters[key] : undefined; if (adapter && key) { const credential = await credentialFor(ctx, key); if (credential) { usage = await adapter.fetch(credential); // A newer header supersedes only its own buckets, not the entire poll. const newer = [...(headerUpdates.get(key)?.values() ?? [])] .filter((update) => update.revision > fetchRevision) .map((update) => update.bucket); if (newer.length) usage = mergeHeaders(usage, { ...usage, buckets: newer }); outcome = usage.buckets.length ? "success" : "unavailable"; if (canPublish()) cache.set(key, usage); } } } catch { usage = key ? cache.get(key) : undefined; outcome = usage ? "cached" : "unavailable"; } return { usage, outcome }; } async function fetchQuota( ctx: ExtensionContext, ticket: number, key: string | undefined, ) { const finish = span?.("quota.fetch"); const canPublish = () => ticket === generation && key === activeKey(ctx) && key === currentProviderKey; const { usage, outcome } = await loadQuota(ctx, key, canPublish); if (!canPublish()) { finish?.("finish", { outcome: "stale" }); return; } quotas = usage ? [usage] : []; lastAttemptAt = Date.now(); finish?.("finish", { outcome }); } async function fetchExtra( ctx: ExtensionContext, ticket: number, key: string, ) { const finish = span?.("quota.fetch"); const canPublish = () => ticket === generation && extras.has(key) && key !== activeKey(ctx); const { usage, outcome } = await loadQuota(ctx, key, canPublish); if (!canPublish()) { finish?.("finish", { outcome: "stale" }); return; } if (usage) extraQuotas.set(key, usage); else extraQuotas.delete(key); finish?.("finish", { outcome }); } function refreshExtra(ctx: ExtensionContext, key: string): Promise { const ticket = generation; const pending = extraFetches.get(key); if (pending?.generation === ticket) return pending.promise; const promise = fetchExtra(ctx, ticket, key).finally(() => { if (extraFetches.get(key)?.promise === promise) extraFetches.delete(key); }); extraFetches.set(key, { generation: ticket, promise }); return promise; } async function getOrFetch(ctx: ExtensionContext, force = false) { if (!force && lastAttemptAt && Date.now() - lastAttemptAt < refreshMs) return; const key = activeKey(ctx); const ticket = generation; let active = fetchPromise?.generation === ticket && fetchPromise.key === key ? fetchPromise.promise : undefined; if (!active) { const promise = fetchQuota(ctx, ticket, key).finally(() => { if (fetchPromise?.promise === promise) fetchPromise = null; }); fetchPromise = { generation: ticket, key, promise }; active = promise; } const pending = [active]; for (const extra of extras) if (extra !== key) pending.push(refreshExtra(ctx, extra)); await Promise.all(pending); } function startRefresh(ctx: ExtensionContext, ticket: number) { if (refreshTimer) clearInterval(refreshTimer); refreshTimer = setInterval(async () => { try { await getOrFetch(ctx, true); if (ticket !== generation) return; updateFooter(ctx); updateWidget(ctx); } catch {} }, refreshMs); } function activate(ctx: ExtensionContext): number { if (!ctx.hasUI) return generation; lastCtx = ctx; const key = activeKey(ctx); const changed = key !== currentProviderKey; if (changed) { generation++; revision++; lastAttemptAt = 0; quotas = []; } currentProviderKey = key; const ticket = generation; ctx.ui.setStatus(STATUS_ID, undefined); if (!refreshTimer || changed) startRefresh(ctx, ticket); void (async () => { try { await getOrFetch(ctx); if (ticket !== generation) return; updateFooter(ctx); updateWidget(ctx); } catch {} })(); return ticket; } pi.registerCommand("quota", { description: "Show/hide subscription quota usage", async handler(_args, ctx) { if (!ctx.hasUI) { ctx.ui.notify("/quota requires interactive mode", "error"); return; } widgetVisible = !widgetVisible; if (!widgetVisible) { ctx.ui.setWidget("usage", undefined); return; } const ticket = activate(ctx); updateWidget(ctx); try { await getOrFetch(ctx, true); if (ticket !== generation || !widgetVisible) return; updateFooter(ctx); updateWidget(ctx); } catch {} }, }); pi.on("session_start", (_event, ctx) => { dbg?.("session.start"); generation++; revision++; currentProviderKey = activeKey(ctx); lastAttemptAt = 0; quotas = []; cache.clear(); headerUpdates.clear(); extras.clear(); extraQuotas.clear(); extraFetches.clear(); lastCtx = ctx.hasUI ? ctx : undefined; widgetVisible = false; if (refreshTimer) clearInterval(refreshTimer); refreshTimer = null; clearFooter(); if (!ctx.hasUI) return; ctx.ui.setWidget("usage", undefined); const setting = resolveSetting(pi, ctx, REFRESH_SETTING); refreshMs = setting.ok ? setting.value : DEFAULT_REFRESH_MS; if (!setting.ok) ctx.ui.notify( `${setting.error}; using ${DEFAULT_REFRESH_MS} ms`, "warning", ); ctx.ui.setStatus(STATUS_ID, undefined); }); pi.events.on(ACTIVITY_EVENT, (data) => { const key = object(data)["provider"]; const ctx = lastCtx; if (!ctx || typeof key !== "string" || !Object.hasOwn(adapters, key)) return; if (!extras.has(key)) { if (extras.size >= MAX_EXTRA_PROVIDERS) return; extras.add(key); } // The active provider already polls; an extra copy would duplicate it. if (key === activeKey(ctx)) return; const ticket = generation; if (!refreshTimer) startRefresh(ctx, ticket); void refreshExtra(ctx, key) .then(() => { if (ticket !== generation) return; updateFooter(ctx); updateWidget(ctx); }) .catch(() => {}); }); pi.on("agent_start", (_event, ctx) => { activate(ctx); updateFooter(ctx); }); pi.on("agent_end", async (_event, ctx) => { if (!ctx.hasUI) return; try { await getOrFetch(ctx); updateFooter(ctx); updateWidget(ctx); } catch {} }); pi.on("message_end", (event, ctx) => { // A router may answer from another provider; follow it without waiting for agent_end. if (!ctx.hasUI || event.message.role !== "assistant") return; if (!isRouted(ctx.model) || activeKey(ctx) === currentProviderKey) return; activate(ctx); updateFooter(ctx); }); pi.on("after_provider_response", (event, ctx) => { // Headers do not name the routed provider; routed selections rely on polling. if (!ctx.hasUI || isRouted(ctx.model)) return; const key = activeKey(ctx); if (!key || key !== currentProviderKey) return; const update = adapters[key]?.headers?.(event.headers); if (!update) return; if (key === "anthropic" || key === "openai-codex") dbg?.("quota.headers", { provider: key, status: event.status }); revision++; const usage = mergeHeaders(cache.get(key), update); const merged = new Map(usage.buckets.map((bucket) => [bucket.id, bucket])); const pending = headerUpdates.get(key) ?? new Map(); for (const bucket of update.buckets) { const complete = merged.get(bucket.id) ?? bucket; if (pending.has(bucket.id) || pending.size < 512) pending.set(bucket.id, { revision, bucket: complete }); } headerUpdates.set(key, pending); cache.set(key, usage); quotas = [usage]; lastAttemptAt = Date.now(); updateFooter(ctx); updateWidget(ctx); }); pi.on("model_select", async (_event, ctx) => { if (!ctx.hasUI) return; const ticket = activate(ctx); try { await getOrFetch(ctx, true); if (ticket !== generation) return; updateFooter(ctx); updateWidget(ctx); } catch {} }); pi.on("session_shutdown", (_event, ctx) => { dbg?.("session.shutdown"); generation++; revision++; currentProviderKey = undefined; lastCtx = undefined; extras.clear(); extraQuotas.clear(); extraFetches.clear(); if (refreshTimer) clearInterval(refreshTimer); refreshTimer = null; widgetVisible = false; clearFooter(); ctx.ui.setStatus(STATUS_ID, undefined); ctx.ui.setWidget("usage", undefined); closeDebug(); }); }