repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/cost/index.ts
Raw/**
* Cost and token footer segments.
*
* Emits into the shared footer "llm" zone:
* - tokens: cumulative session token and cache usage
* - cost: turn/session/monthly spend when non-zero
*/
import type { Dirent } from "node:fs";
import { readdir, readFile, stat } from "node:fs/promises";
import { dirname, join, resolve } from "node:path";
import type { Api, Model } from "@earendil-works/pi-ai";
import { calculateCost } from "@earendil-works/pi-ai";
import type {
ExtensionAPI,
ExtensionContext,
ThemeColor,
} from "@earendil-works/pi-coding-agent";
import {
getAgentDir,
parseSessionEntries,
} from "@earendil-works/pi-coding-agent";
import { closeDebug, dbg, span } from "./src/debug.ts";
import {
offerFooterSegment,
removeFooterSegment,
} from "./src/pi-ext-footer-segment.ts";
// ── Constants ─────────────────────────────────────────────────────────────
const STATUS_ID = "cost";
const CACHE_ICON = "";
const COUNT_DECIMAL_THRESHOLD = 1_000;
const COUNT_ROUND_THRESHOLD = 10_000;
const MILLION_THRESHOLD = 1_000_000;
const MILLION_DECIMAL_THRESHOLD = 10_000_000;
const LOW_COST_THRESHOLD = 0.01;
const MEDIUM_COST_THRESHOLD = 10;
const HIGH_COST_THRESHOLD = 1_000;
const SESSION_EXT = ".jsonl";
const FOOTER = {
tokens: { id: "tokens", color: "muted", order: 2 },
cost: { id: "cost", color: "success", order: 3 },
zone: "llm",
} as const satisfies Record<string, unknown>;
const UPDATE_EVENTS = [
"agent_start",
"agent_end",
"tool_execution_end",
] as const;
const RESET_SIGNATURE_EVENTS = [
"model_select",
"session_compact",
"session_tree",
] as const;
// ── Types ─────────────────────────────────────────────────────────────────
type TokenUsage = {
input: number;
output: number;
cacheRead: number;
cacheWrite: number;
};
type UsageWithCost = Partial<TokenUsage> & {
cost?: { total?: number; totalFromProvider?: boolean };
};
type AssistantLikeMessage = {
role?: unknown;
usage?: UsageWithCost;
provider?: string;
model?: string;
responseModel?: string;
timestamp?: unknown;
responseId?: string;
toolCallId?: string;
toolName?: string;
};
type Snapshot = {
usage: TokenUsage;
cacheHitRate?: number | undefined;
turnCost: number;
sessionCost: number;
monthlyCost: number;
turnTotalFromProvider?: boolean;
sessionTotalFromProvider?: boolean;
monthlyTotalFromProvider?: boolean;
};
type SegmentId = "tokens" | "cost";
/** Catalog lookup, normally `ctx.modelRegistry.find`. */
type FindModel = (provider: string, modelId: string) => Model<Api> | undefined;
type MonthlyUsageCost = {
identity: string | undefined;
cost: number;
totalFromProvider: boolean;
};
type MonthlyCostCache = Map<
string,
{
mtimeMs: number;
size: number;
month: string;
usage: MonthlyUsageCost[];
}
>;
// ── Pricing ───────────────────────────────────────────────────────────────
/** Catalog fallback for unbilled zero totals; unknown models cost 0. */
function catalogTokenCost(
model: Model<Api> | undefined,
usage: TokenUsage,
): number {
if (!model) return 0;
// calculateCost writes into usage.cost, so hand it a private copy.
return calculateCost(model, {
...usage,
totalTokens:
usage.input + usage.output + usage.cacheRead + usage.cacheWrite,
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
}).total;
}
// ── Message extraction ────────────────────────────────────────────────────
function isAssistantMessageEntry(
entry: unknown,
): entry is { type: "message"; message: AssistantLikeMessage } {
const candidate = entry as
| { type?: unknown; message?: AssistantLikeMessage }
| undefined;
return (
candidate?.type === "message" && candidate.message?.role === "assistant"
);
}
function normalizeUsage(usage: UsageWithCost | undefined): TokenUsage {
return {
input: usage?.input ?? 0,
output: usage?.output ?? 0,
cacheRead: usage?.cacheRead ?? 0,
cacheWrite: usage?.cacheWrite ?? 0,
};
}
function messageCost(
message: AssistantLikeMessage,
findModel: FindModel,
): number {
const reported = message.usage?.cost?.total ?? 0;
if (message.usage?.cost?.totalFromProvider === true || reported > 0)
return reported;
// Router responses may name a concrete model absent from the local catalog.
// Prefer its prices; retain the requested model's historical estimate otherwise.
const provider = message.provider ?? "";
const requested = message.model ?? "";
const responder = message.responseModel;
return catalogTokenCost(
(responder ? findModel(provider, responder) : undefined) ??
findModel(provider, requested),
normalizeUsage(message.usage),
);
}
function entryCost(entry: unknown, findModel: FindModel): number | undefined {
if (isAssistantMessageEntry(entry))
return messageCost(entry.message, findModel);
if ((entry as { type?: unknown })?.type === "usage")
return messageCost(entry as AssistantLikeMessage, findModel);
return usageFromEntry(entry)?.cost?.total;
}
function sumMessageCosts(
entries: readonly unknown[],
findModel: FindModel,
): number {
let total = 0;
for (const entry of entries) total += entryCost(entry, findModel) ?? 0;
return total;
}
function usageFromEntry(entry: unknown): UsageWithCost | undefined {
const candidate = entry as
| {
type?: unknown;
message?: { role?: unknown; usage?: UsageWithCost };
usage?: UsageWithCost;
}
| undefined;
if (candidate?.type === "message") {
if (
candidate.message?.role === "assistant" ||
candidate.message?.role === "toolResult"
)
return candidate.message.usage;
return undefined;
}
if (
candidate?.type === "compaction" ||
candidate?.type === "branch_summary" ||
candidate?.type === "usage"
)
return candidate.usage;
return undefined;
}
function allCostsFromProvider(entries: readonly unknown[]): boolean {
let totalFromProvider: boolean | undefined;
for (const entry of entries) {
const usage = usageFromEntry(entry);
if (!usage) continue;
totalFromProvider =
totalFromProvider === undefined
? usage.cost?.totalFromProvider === true
: totalFromProvider && usage.cost?.totalFromProvider === true;
}
return totalFromProvider === true;
}
function sessionUsage(entries: readonly unknown[]): TokenUsage {
const total: TokenUsage = {
input: 0,
output: 0,
cacheRead: 0,
cacheWrite: 0,
};
for (const entry of entries) {
const usage = normalizeUsage(usageFromEntry(entry));
total.input += usage.input;
total.output += usage.output;
total.cacheRead += usage.cacheRead;
total.cacheWrite += usage.cacheWrite;
}
return total;
}
function latestAssistantCacheHitRate(
entries: readonly unknown[],
): number | undefined {
for (let i = entries.length - 1; i >= 0; i--) {
const entry = entries[i];
if (!isAssistantMessageEntry(entry) || !entry.message.usage) continue;
const usage = normalizeUsage(entry.message.usage);
const prompt = usage.input + usage.cacheRead + usage.cacheWrite;
return prompt > 0 ? (usage.cacheRead / prompt) * 100 : undefined;
}
return undefined;
}
// ── Session file scan ─────────────────────────────────────────────────────
async function safeReadDir(path: string): Promise<Dirent[]> {
try {
return await readdir(path, { withFileTypes: true });
} catch {
dbg?.("monthly.file", { outcome: "directory_failed" });
return [];
}
}
function currentMonthKey(date = new Date()): string {
return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
}
function isSessionFile(file: Dirent): boolean {
return file.isFile() && file.name.endsWith(SESSION_EXT);
}
async function sessionFiles(
sessionDir: string,
isCurrent: () => boolean,
): Promise<string[] | undefined> {
const files: string[] = [];
// Same stores as SessionManager.listAll, without its full per-session parse:
// Pi's default store nests one directory per project; a configured store is flat.
const root = join(getAgentDir(), "sessions");
const custom = !!sessionDir && resolve(dirname(sessionDir)) !== resolve(root);
const dirs = custom
? [sessionDir]
: (await safeReadDir(root))
.filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
.map((entry) => join(root, entry.name));
for (const childDir of dirs) {
for (const file of await safeReadDir(childDir)) {
if (!isCurrent()) return undefined;
if (isSessionFile(file)) files.push(join(childDir, file.name));
}
}
return files;
}
function entryTimestamp(entry: {
timestamp?: unknown;
message?: AssistantLikeMessage;
}): number | undefined {
for (const raw of [entry.message?.timestamp, entry.timestamp]) {
const timestamp =
typeof raw === "number"
? raw
: typeof raw === "string"
? Date.parse(raw)
: NaN;
if (Number.isFinite(timestamp)) return timestamp;
}
return undefined;
}
// Fork copies preserve record identity, but may rewrite parent/session linkage.
// Without persisted identity, retain ambiguous records rather than lose spending.
function usageIdentity(entry: {
id?: unknown;
timestamp?: unknown;
type?: unknown;
message?: AssistantLikeMessage;
kind?: unknown;
provider?: unknown;
model?: unknown;
usage?: UsageWithCost;
}): string | undefined {
if (
typeof entry.id !== "string" ||
!entry.id ||
typeof entry.timestamp !== "string" ||
!Number.isFinite(Date.parse(entry.timestamp))
)
return undefined;
const message = entry.message;
return JSON.stringify([
entry.id,
entry.timestamp,
entry.type,
message?.role,
message?.provider,
message?.model,
message?.responseModel,
message?.timestamp,
message?.responseId,
message?.toolCallId,
message?.toolName,
message?.usage ?? entry.usage,
entry.kind,
entry.provider,
entry.model,
]);
}
async function readMonthlyUsage(
filePath: string,
findModel: FindModel,
month: string,
): Promise<MonthlyUsageCost[] | undefined> {
try {
const usage: MonthlyUsageCost[] = [];
const entries = parseSessionEntries(await readFile(filePath, "utf-8"));
for (const entry of entries) {
const recorded = usageFromEntry(entry);
if (!recorded) continue;
const timestamp = entryTimestamp(entry);
if (
timestamp === undefined ||
currentMonthKey(new Date(timestamp)) !== month
)
continue;
usage.push({
identity: usageIdentity(entry),
cost: entryCost(entry, findModel) ?? 0,
totalFromProvider: recorded.cost?.totalFromProvider === true,
});
}
return usage;
} catch {
dbg?.("monthly.file", { outcome: "parse_failed" });
return undefined;
}
}
async function calculateMonthlyCost(
sessionDir: string,
findModel: FindModel,
isCurrent: () => boolean = () => true,
cache: MonthlyCostCache = new Map(),
onProvenance?: (totalFromProvider: boolean) => void,
): Promise<number | undefined> {
if (!isCurrent()) return undefined;
const month = currentMonthKey();
const files = await sessionFiles(sessionDir, isCurrent);
if (!files) return undefined;
const next: MonthlyCostCache = new Map();
const seen = new Set<string>();
let total = 0;
let totalFromProvider: boolean | undefined;
for (const file of files) {
if (!isCurrent()) return undefined;
try {
const { mtimeMs, size } = await stat(file);
if (!isCurrent()) return undefined;
const cached = cache.get(file);
const isCached =
cached?.mtimeMs === mtimeMs &&
cached.size === size &&
cached.month === month;
const usage = isCached
? cached.usage
: await readMonthlyUsage(file, findModel, month);
if (isCached) dbg?.("monthly.file", { outcome: "cached" });
else if (usage !== undefined) dbg?.("monthly.file", { outcome: "read" });
if (usage === undefined) continue;
next.set(file, { mtimeMs, size, month, usage });
for (const record of usage) {
if (record.identity !== undefined) {
if (seen.has(record.identity)) continue;
seen.add(record.identity);
}
total += record.cost;
totalFromProvider =
totalFromProvider === undefined
? record.totalFromProvider
: totalFromProvider && record.totalFromProvider;
}
} catch {
dbg?.("monthly.file", { outcome: "stat_failed" });
// Deleted or inaccessible files are retried on the next refresh.
}
}
if (!isCurrent() || month !== currentMonthKey()) return undefined;
cache.clear();
for (const [file, subtotal] of next) cache.set(file, subtotal);
onProvenance?.(totalFromProvider === true);
return total;
}
// ── Formatting ────────────────────────────────────────────────────────────
/** Human-readable token count: 978, 1.1k, 448k, 1.6M, 122M. */
function formatCount(value: number): string {
if (value < COUNT_DECIMAL_THRESHOLD) return `${value}`;
if (value < COUNT_ROUND_THRESHOLD)
return `${(value / COUNT_DECIMAL_THRESHOLD).toFixed(1)}k`;
if (value < MILLION_THRESHOLD)
return `${Math.round(value / COUNT_DECIMAL_THRESHOLD)}k`;
if (value < MILLION_DECIMAL_THRESHOLD)
return `${(value / MILLION_THRESHOLD).toFixed(1)}M`;
return `${Math.round(value / MILLION_THRESHOLD)}M`;
}
function formatCost(value: number, totalFromProvider = false): string {
if (!totalFromProvider) return `≈${formatCost(value, true)}`;
if (value < LOW_COST_THRESHOLD) return `$${value.toFixed(4)}`;
if (value < MEDIUM_COST_THRESHOLD) return `$${value.toFixed(2)}`;
if (value < HIGH_COST_THRESHOLD) return `$${value.toFixed(1)}`;
return `$${(value / HIGH_COST_THRESHOLD).toFixed(1)}k`;
}
/**
* Cumulative prompt and completion volume. Cache reads and writes are omitted
* on purpose: as raw totals they are unreadable and unactionable, while the
* cache hit rate already carries the only decision-relevant part.
*/
function tokenLabel(usage: TokenUsage, cacheHitRate?: number): string {
if (
usage.input === 0 &&
usage.output === 0 &&
usage.cacheRead === 0 &&
usage.cacheWrite === 0
)
return "↑0";
const parts: string[] = [];
if (usage.input > 0) parts.push(`↑${formatCount(usage.input)}`);
if (usage.output > 0) parts.push(`↓${formatCount(usage.output)}`);
if (cacheHitRate !== undefined)
parts.push(`${CACHE_ICON} ${Math.round(cacheHitRate)}%`);
return parts.join(" ");
}
function costLabel(snapshot: Snapshot): string | undefined {
const parts: string[] = [];
if (snapshot.turnCost > 0)
parts.push(formatCost(snapshot.turnCost, snapshot.turnTotalFromProvider));
if (snapshot.sessionCost > 0)
parts.push(
`Σ${formatCost(snapshot.sessionCost, snapshot.sessionTotalFromProvider)}`,
);
if (snapshot.monthlyCost > 0 && snapshot.monthlyCost !== snapshot.sessionCost)
parts.push(
` ${formatCost(snapshot.monthlyCost, snapshot.monthlyTotalFromProvider)}`,
);
return parts.length > 0 ? parts.join(" · ") : undefined;
}
// ── Footer emission ───────────────────────────────────────────────────────
function emitSegment(
pi: ExtensionAPI,
id: SegmentId,
text: string | undefined,
): boolean {
if (text === undefined) return removeFooterSegment(pi, FOOTER[id].id);
return offerFooterSegment(pi, {
id: FOOTER[id].id,
text,
color: FOOTER[id].color as ThemeColor,
zone: FOOTER.zone,
order: FOOTER[id].order,
});
}
/** TUI fallback when the footer rejects the segments; glyphs stay readable. */
function statusLabel(snapshot: Snapshot): string {
return [
tokenLabel(snapshot.usage, snapshot.cacheHitRate),
costLabel(snapshot),
]
.filter((part): part is string => !!part)
.join(" · ");
}
/**
* Non-TUI label: words instead of arrows and private-use icons, because RPC
* clients render the status line as plain text in an unknown font.
*/
function plainLabel(snapshot: Snapshot): string {
const { input, output } = snapshot.usage;
const parts = [`in ${formatCount(input)}`, `out ${formatCount(output)}`];
if (snapshot.cacheHitRate !== undefined)
parts.push(`cache hit ${Math.round(snapshot.cacheHitRate)}%`);
if (snapshot.turnCost > 0)
parts.push(
`turn ${formatCost(snapshot.turnCost, snapshot.turnTotalFromProvider)}`,
);
if (snapshot.sessionCost > 0)
parts.push(
`session ${formatCost(snapshot.sessionCost, snapshot.sessionTotalFromProvider)}`,
);
if (snapshot.monthlyCost > 0 && snapshot.monthlyCost !== snapshot.sessionCost)
parts.push(
`month ${formatCost(snapshot.monthlyCost, snapshot.monthlyTotalFromProvider)}`,
);
return parts.join(", ");
}
function publishSnapshot(
pi: ExtensionAPI,
ctx: ExtensionContext,
snapshot: Snapshot,
) {
if (ctx.mode !== "tui") {
clearSegments(pi);
ctx.ui.setStatus(STATUS_ID, plainLabel(snapshot));
return;
}
const tokensAccepted = emitSegment(
pi,
"tokens",
tokenLabel(snapshot.usage, snapshot.cacheHitRate),
);
const costAccepted = emitSegment(pi, "cost", costLabel(snapshot));
const accepted = tokensAccepted && costAccepted;
if (!accepted) clearSegments(pi);
ctx.ui.setStatus(STATUS_ID, accepted ? undefined : statusLabel(snapshot));
}
function clearSegments(pi: ExtensionAPI) {
emitSegment(pi, "tokens", undefined);
emitSegment(pi, "cost", undefined);
}
function clearPublished(pi: ExtensionAPI, ctx?: ExtensionContext) {
clearSegments(pi);
if (ctx?.hasUI) ctx.ui.setStatus(STATUS_ID, undefined);
}
// ── Snapshot ──────────────────────────────────────────────────────────────
function buildSnapshot(
ctx: ExtensionContext,
previousSessionCost: number,
monthlyCost: number,
previousEntryCount: number,
monthlyTotalFromProvider: boolean,
): Snapshot {
const entries = ctx.sessionManager.getEntries();
const sessionCost = sumMessageCosts(entries, registryLookup(ctx));
return {
usage: sessionUsage(entries),
cacheHitRate: latestAssistantCacheHitRate(entries),
turnCost: Math.max(0, sessionCost - previousSessionCost),
sessionCost,
monthlyCost,
turnTotalFromProvider: allCostsFromProvider(
entries.slice(previousEntryCount),
),
sessionTotalFromProvider: allCostsFromProvider(entries),
monthlyTotalFromProvider,
};
}
function registryLookup(ctx: ExtensionContext): FindModel {
return (provider, modelId) => ctx.modelRegistry.find(provider, modelId);
}
function signature(snapshot: Snapshot): string {
const usage = snapshot.usage;
return [
usage.input,
usage.output,
usage.cacheRead,
usage.cacheWrite,
snapshot.cacheHitRate,
snapshot.sessionCost,
snapshot.monthlyCost,
snapshot.sessionTotalFromProvider,
snapshot.monthlyTotalFromProvider,
].join("|");
}
// ── Extension ─────────────────────────────────────────────────────────────
export default function costExtension(pi: ExtensionAPI): void {
let previousSessionCost = 0;
let monthlyCost = 0;
let monthlyTotalFromProvider = false;
let previousEntryCount = 0;
let lastSignature = "";
let hasUI = false;
let generation = 0;
const monthlyCache: MonthlyCostCache = new Map();
let refreshRunning = false;
let pendingRefresh: { ctx: ExtensionContext; ticket: number } | undefined;
function requestMonthlyRefresh(ctx: ExtensionContext) {
if (!hasUI) return;
pendingRefresh = { ctx, ticket: generation };
if (refreshRunning) return;
refreshRunning = true;
setTimeout(() => {
void (async () => {
while (pendingRefresh) {
const { ctx: refreshCtx, ticket } = pendingRefresh;
pendingRefresh = undefined;
const finish = span?.("monthly.refresh");
try {
const total = await calculateMonthlyCost(
refreshCtx.sessionManager.getSessionDir(),
registryLookup(refreshCtx),
() => ticket === generation,
monthlyCache,
(value) => {
monthlyTotalFromProvider = value;
},
);
if (total === undefined || ticket !== generation) {
finish?.("finish", { outcome: "cancelled" });
continue;
}
monthlyCost = total;
await syncBestEffort(refreshCtx);
finish?.();
} catch {
finish?.("error");
// Background telemetry must never disturb the agent loop.
}
}
refreshRunning = false;
})();
}, 0);
}
async function sync(ctx: ExtensionContext) {
if (!hasUI) return;
const snapshot = buildSnapshot(
ctx,
previousSessionCost,
monthlyCost,
previousEntryCount,
monthlyTotalFromProvider,
);
previousSessionCost = snapshot.sessionCost;
previousEntryCount = ctx.sessionManager.getEntries().length;
const nextSignature = signature(snapshot);
if (nextSignature === lastSignature) return;
lastSignature = nextSignature;
publishSnapshot(pi, ctx, snapshot);
}
async function syncBestEffort(ctx: ExtensionContext) {
try {
await sync(ctx);
} catch {
// Footer telemetry must never disturb the agent loop.
}
}
pi.on("session_start", (_event, ctx) => {
const ticket = ++generation;
dbg?.("session.start");
hasUI = ctx.hasUI;
if (!hasUI) return;
previousSessionCost = 0;
lastSignature = "";
monthlyCost = 0;
monthlyTotalFromProvider = false;
previousEntryCount = 0;
monthlyCache.clear();
setTimeout(() => {
if (ticket !== generation) return;
void syncBestEffort(ctx);
}, 0);
requestMonthlyRefresh(ctx);
});
for (const eventName of UPDATE_EVENTS) {
pi.on(eventName as any, async (_event: any, ctx: any) => {
await syncBestEffort(ctx);
if (eventName === "agent_end") requestMonthlyRefresh(ctx);
});
}
for (const eventName of RESET_SIGNATURE_EVENTS) {
pi.on(eventName as any, async (_event: any, ctx: any) => {
lastSignature = "";
await syncBestEffort(ctx);
});
}
pi.on("session_shutdown", async (_event, ctx) => {
generation++;
hasUI = false;
pendingRefresh = undefined;
monthlyCache.clear();
clearPublished(pi, ctx);
dbg?.("session.shutdown");
closeDebug();
});
}
export const __test: {
calculateMonthlyCost: typeof calculateMonthlyCost;
allCostsFromProvider: typeof allCostsFromProvider;
costLabel: typeof costLabel;
latestAssistantCacheHitRate: typeof latestAssistantCacheHitRate;
plainLabel: typeof plainLabel;
sessionUsage: typeof sessionUsage;
sumMessageCosts: typeof sumMessageCosts;
tokenLabel: typeof tokenLabel;
} = {
calculateMonthlyCost,
allCostsFromProvider,
costLabel,
latestAssistantCacheHitRate,
plainLabel,
sessionUsage,
sumMessageCosts,
tokenLabel,
};