@pify/usage 0.8.0 → 0.8.1

package/README.md

@@ -62,6 +62,8 @@ Computed entirely from what pi already holds: the assembled system prompt, the f
 
 Context files and skills are counted only when their text is genuinely embedded in the prompt, and the system-prompt row is the remainder after subtracting them, so the rows sum to the whole instead of double-counting. When the provider reports more than can be attributed, the difference is shown as **Other** rather than quietly dropped.
 
+The "used" figure and the footer gauge are reconciled across three signals — pi's own `getContextUsage()` reading, the provider's last-request report, and the local content estimate — so a backend that reports a wrong number (a cumulative or cache-inflated total, or an implausibly small one) can't throw the gauge off: the provider's report is used when it agrees with pi's percent×window, pi's reading is trusted when they diverge beyond tolerance, and the figure is never allowed below the tokens visibly in context. (The reconciliation rule is from minuque/pi-cc-extensions.)
+
 Reasoning gets its own **Thinking** row rather than hiding inside Conversation — on keep-thinking models it is a large, otherwise-invisible share (the opaque signature bytes are never counted or stored). And when pi's auto-compaction is on, the tokens it holds back appear as a **Compaction reserve** row and are subtracted from **Free space**, so the headroom shown is what you can actually use before compaction fires.
 
 ## `/usage quota`

package/extensions/usage.ts

@@ -29,7 +29,7 @@ import { join } from "node:path";
 import { readFileSync } from "node:fs";
 
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
-import { buildBreakdown, formatBreakdown } from "../src/context.ts";
+import { buildBreakdown, formatBreakdown, resolveUsedTokens } from "../src/context.ts";
 import { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
 import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
 import { redact } from "../src/redact.ts";
@@ -73,9 +73,20 @@ export default function usage(pi: ExtensionAPI) {
   }
 
   function contextPct(ctx: UiContext): number | null {
-    const window = (ctx.model as { contextWindow?: number } | null)?.contextWindow;
-    if (!window || lastPromptTokens === 0) return null;
-    return Math.min(100, (lastPromptTokens / window) * 100);
+    const usage = (
+      ctx as { getContextUsage?: () => { tokens?: number | null; contextWindow?: number; percent?: number | null } | undefined }
+    ).getContextUsage?.();
+    const window = usage?.contextWindow ?? (ctx.model as { contextWindow?: number } | null)?.contextWindow ?? 0;
+    // Reconcile pi's own reading with the provider's last-request report, rather
+    // than trusting the provider number blind (some backends report it wrong).
+    const used = resolveUsedTokens({
+      hostTokens: usage?.tokens ?? null,
+      hostPercent: usage?.percent ?? null,
+      window,
+      providerTokens: lastPromptTokens || null,
+    });
+    if (used === null || window <= 0) return null;
+    return Math.min(100, (used / window) * 100);
   }
 
   function dashboard(ctx: UiContext): string {
@@ -173,7 +184,7 @@ export default function usage(pi: ExtensionAPI) {
         skills?: unknown[];
         selectedTools?: string[];
       };
-      getContextUsage?: () => { contextWindow?: number; used?: number; total?: number } | undefined;
+      getContextUsage?: () => { tokens?: number | null; contextWindow?: number; percent?: number | null } | undefined;
       sessionManager?: { buildContextEntries?: () => unknown[]; getBranch?: () => unknown[] };
     };
 
@@ -204,7 +215,17 @@ export default function usage(pi: ExtensionAPI) {
       contextWindow,
       reserveTokens: compactionReserve(ctx),
     });
-    const reported = typeof usage?.used === "number" ? usage.used : lastPromptTokens || null;
+    // The provider's real last-request number is the primary "used" figure (it
+    // makes the "Other" row — what the provider counts that we can't attribute —
+    // meaningful), reconciled against pi's own reading and floored by the local
+    // estimate so a wrong provider total can't over- or under-state the window.
+    const reported = resolveUsedTokens({
+      hostTokens: usage?.tokens ?? null,
+      hostPercent: usage?.percent ?? null,
+      window: contextWindow,
+      providerTokens: lastPromptTokens || null,
+      estimate: breakdown.attributed,
+    });
     return formatBreakdown(breakdown, reported);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Token and cost reporting for pi sessions: live footer, local-history dashboard with per-project costs, opt-in provider quota",
   "keywords": [
     "pi-package",

package/src/context.ts

@@ -149,6 +149,58 @@ export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
   };
 }
 
+export interface UsedTokensInput {
+  /** pi's own estimate of context tokens (getContextUsage().tokens), or null. */
+  hostTokens: number | null;
+  /** pi's own percent-of-window (getContextUsage().percent), or null. */
+  hostPercent: number | null;
+  /** The context window; 0 when unknown. */
+  window: number;
+  /** The provider's report for the last request (input + cacheRead), or null. */
+  providerTokens: number | null;
+  /** A local content estimate (a hard lower bound), when one is available. */
+  estimate?: number;
+}
+
+/**
+ * Reconcile the several "how full is the window" signals into one used-tokens
+ * figure, so the gauge does not blindly trust a provider number that some
+ * backends report wrong (cumulative totals, cache-inflated counts, or an
+ * implausibly small figure). The rule — from minuque/pi-cc-extensions'
+ * resolveUsedTokens:
+ *
+ *  - the provider's report is the primary signal (it is the real last request),
+ *  - but when it diverges beyond tolerance from pi's own percent×window reading
+ *    (what pi itself uses for the gauge and for compaction), trust pi's number,
+ *  - and never report fewer tokens than the content visibly in context.
+ *
+ * Returns null only when nothing is known (so the gauge can hide itself).
+ */
+export function resolveUsedTokens(input: UsedTokensInput): number | null {
+  const w = input.window > 0 ? input.window : 0;
+  const fromPercent = input.hostPercent !== null && w > 0 ? (input.hostPercent / 100) * w : null;
+  const host = input.hostTokens !== null ? input.hostTokens : fromPercent;
+  const provider = input.providerTokens !== null && input.providerTokens > 0 ? input.providerTokens : null;
+  const estimate = typeof input.estimate === "number" && input.estimate > 0 ? input.estimate : null;
+
+  let used = provider ?? host ?? estimate;
+  if (used === null || used === undefined) return null;
+
+  // Trust pi's own reading when the provider's number diverges beyond tolerance
+  // (25% of the host reading, or 2k tokens, whichever is larger).
+  if (provider !== null && host !== null) {
+    const tolerance = Math.max(2000, host * 0.25);
+    if (Math.abs(provider - host) > tolerance) used = host;
+  }
+
+  // A content estimate is a hard floor: you cannot be using fewer tokens than
+  // the text that is demonstrably in context.
+  if (estimate !== null && estimate > used) used = estimate;
+
+  if (w > 0) used = Math.min(used, w);
+  return Math.max(0, Math.round(used));
+}
+
 const BAR_WIDTH = 28;
 
 function bar(fraction: number): string {