repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/quota/index.ts
Raw/** /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<number> = 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<void>;
} | null = null;
let widgetVisible = false;
let refreshTimer: ReturnType<typeof setInterval> | null = null;
let refreshMs = DEFAULT_REFRESH_MS;
let generation = 0;
let revision = 0;
let currentProviderKey: string | undefined;
const cache = new Map<string, ProviderQuota>();
const headerUpdates = new Map<
string,
Map<string, { revision: number; bucket: QuotaBucket }>
>();
const footerIds = new Set<string>();
// Session-scoped secondary providers; shown beside, never instead of, the active one.
const extras = new Set<string>();
const extraQuotas = new Map<string, ProviderQuota>();
const extraFetches = new Map<
string,
{ generation: number; promise: Promise<void> }
>();
// 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<string>();
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<string | undefined> {
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<void> {
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<string, { revision: number; bucket: QuotaBucket }>();
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();
});
}