@pify/usage 0.7.2 → 0.8.1

package/README.md

@@ -62,6 +62,10 @@ 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`
 
 The one command here that touches the network, and only when you run it:

package/extensions/usage.ts

@@ -20,6 +20,7 @@
 import {
   formatSkillsForPrompt,
   getAgentDir,
+  SettingsManager,
   type ExtensionAPI,
   type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
@@ -28,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";
@@ -72,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 {
@@ -150,6 +162,20 @@ export default function usage(pi: ExtensionAPI) {
    * it, the enabled tool definitions, and the entries that would be sent.
    * No network, no model call — same rule as the rest of the package.
    */
+  /**
+   * Tokens pi holds back for auto-compaction, so "Free space" reflects real
+   * headroom. Best-effort: 0 when compaction is off or the API is unavailable.
+   */
+  function compactionReserve(ctx: UiContext): number {
+    try {
+      const projectTrusted = (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() ?? false;
+      const settings = SettingsManager.create(ctx.cwd, getAgentDir(), { projectTrusted });
+      return settings.getCompactionEnabled() ? Math.max(0, settings.getCompactionReserveTokens()) : 0;
+    } catch {
+      return 0;
+    }
+  }
+
   function contextBreakdown(ctx: UiContext): string {
     const host = ctx as unknown as {
       getSystemPrompt?: () => string;
@@ -158,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[] };
     };
 
@@ -187,8 +213,19 @@ export default function usage(pi: ExtensionAPI) {
       tools,
       entries,
       contextWindow,
+      reserveTokens: compactionReserve(ctx),
+    });
+    // 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,
     });
-    const reported = typeof usage?.used === "number" ? usage.used : lastPromptTokens || null;
     return formatBreakdown(breakdown, reported);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.7.2",
+  "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

@@ -26,6 +26,8 @@ export interface ContextBreakdown {
   /** Sum of every attributed part. */
   attributed: number;
   contextWindow: number;
+  /** Tokens pi holds back for auto-compaction; free space excludes them. */
+  reserveTokens: number;
 }
 
 /** pi's own compaction estimate: four characters per token. */
@@ -52,6 +54,8 @@ export interface BreakdownInput {
   /** Entries pi would send as conversation this turn. */
   entries: unknown[];
   contextWindow: number;
+  /** Tokens pi reserves for auto-compaction (0 when compaction is off). */
+  reserveTokens?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -63,9 +67,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  * Tool results are the part that grows without anyone deciding it should,
  * which is exactly why they deserve their own row.
  */
-function foldEntries(entries: unknown[]): { conversation: number; toolResults: number } {
+function foldEntries(entries: unknown[]): { conversation: number; toolResults: number; thinking: number } {
   let conversation = 0;
   let toolResults = 0;
+  let thinking = 0;
 
   for (const entry of entries) {
     if (!isRecord(entry)) continue;
@@ -84,7 +89,10 @@ function foldEntries(entries: unknown[]): { conversation: number; toolResults: n
         } else if (block.type === "text") {
           conversation += estimateTextTokens(block.text);
         } else if (block.type === "thinking") {
-          conversation += estimateTextTokens(block.thinking);
+          // Reasoning tokens are their own line — on keep-thinking models they
+          // are a large, invisible share otherwise buried in "Conversation".
+          // The opaque signature bytes are deliberately never counted or kept.
+          thinking += estimateTextTokens(block.thinking);
         }
       }
       continue;
@@ -100,7 +108,7 @@ function foldEntries(entries: unknown[]): { conversation: number; toolResults: n
     if (role) conversation += estimateTextTokens(message.content ?? message);
   }
 
-  return { conversation, toolResults };
+  return { conversation, toolResults, thinking };
 }
 
 export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
@@ -119,7 +127,7 @@ export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
       }),
     0,
   );
-  const { conversation, toolResults } = foldEntries(input.entries);
+  const { conversation, toolResults, thinking } = foldEntries(input.entries);
   // Memory and skills live inside the prompt; subtract so rows do not overlap.
   const system = Math.max(0, estimateTextTokens(input.systemPrompt) - memory - skills);
 
@@ -129,6 +137,7 @@ export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
     { label: "Skills", tokens: skills },
     { label: "Tool definitions", tokens: tools },
     { label: "Tool results", tokens: toolResults },
+    { label: "Thinking", tokens: thinking },
     { label: "Conversation", tokens: conversation },
   ];
 
@@ -136,9 +145,62 @@ export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
     parts,
     attributed: parts.reduce((sum, part) => sum + part.tokens, 0),
     contextWindow: Math.max(0, input.contextWindow),
+    reserveTokens: Math.max(0, input.reserveTokens ?? 0),
   };
 }
 
+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 {
@@ -168,10 +230,15 @@ export function formatBreakdown(breakdown: ContextBreakdown, reportedUsed: numbe
   const window = breakdown.contextWindow;
   const used = Math.max(reportedUsed ?? 0, breakdown.attributed);
   const other = Math.max(0, used - breakdown.attributed);
-  const free = window > 0 ? Math.max(0, window - used) : 0;
+  // pi holds back a reserve for auto-compaction; real headroom excludes it, so
+  // show it as its own row and subtract it from free space rather than letting
+  // "Free space" overstate what you can actually use before compaction fires.
+  const reserve = window > 0 ? Math.min(breakdown.reserveTokens, Math.max(0, window - used)) : 0;
+  const free = window > 0 ? Math.max(0, window - used - reserve) : 0;
 
   const rows = [...breakdown.parts];
   if (other > 0) rows.push({ label: "Other", tokens: other });
+  if (reserve > 0) rows.push({ label: "Compaction reserve", tokens: reserve });
   if (window > 0) rows.push({ label: "Free space", tokens: free });
 
   const width = rows.reduce((m, row) => Math.max(m, row.label.length), 0);