@pify/usage 0.12.1 → 0.13.0

package/README.md

@@ -64,10 +64,20 @@ Context window: 22.6k of 200.0k used (11%)
   Tool results      ██··························   8%  16.8k
   Conversation      ····························   1%  2.4k
   Free space        █████████████████████████···  89%  177.4k
+
+Heaviest tool schemas (14 tools, ~3.9k of the prefix):
+  mcp__docs__search     1.6k  mcp:docs
+  workflow              520
+  mcp__docs__fetch      410   mcp:docs
+  bash                  290
+  … and 10 more, ~1.1k
+  by source: mcp:docs ~2.0k, builtin/ext ~1.9k
 ```
 
 "Why am I at 60%?" usually has a boring answer — one `read` of a 4,000-line file — and this is where you find it.
 
+The **Tool definitions** row is broken out below the window into its heaviest tools, biggest first, so a fat MCP schema or a costly server is nameable rather than a lump: every active tool's `name + description + parameters` is a prefix cost paid on *every* request, and the `by source` line totals the builtins and extensions against each MCP server. (This is the live, per-session version of what the cross-harness "subagent-tax" measures.)
+
 Computed entirely from what pi already holds: the assembled system prompt, the files and skills embedded in it, the enabled tool definitions, and the entries that would be sent. No network, no model call.
 
 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. Image blocks (a `read` of a screenshot, a pasted image) are charged at pi's flat 4,800 chars each, not at the size of their base64 bytes, so one screenshot no longer reads as hundreds of thousands of tokens.

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, contextTokensFromUsage, formatBreakdown, resolveUsedTokens } from "../src/context.ts";
+import { buildBreakdown, contextTokensFromUsage, formatBreakdown, formatToolTax, resolveUsedTokens } from "../src/context.ts";
 import { contextGauge, footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
 import { childSpendTotal, onChildSpend, resetChildSpend } from "../src/child-cost.ts";
 import { buildByDayCsv, buildByModelCsv, buildByProjectCsv, buildTotalsJson } from "../src/export.ts";
@@ -281,7 +281,8 @@ export default function usage(pi: ExtensionAPI) {
     const systemPrompt = host.getSystemPrompt?.() ?? "";
     const options = host.getSystemPromptOptions?.() ?? {};
     const selected = new Set(options.selectedTools ?? []);
-    const allTools = (pi as unknown as { getAllTools?: () => Array<{ name?: string }> }).getAllTools?.() ?? [];
+    const allTools =
+      (pi as unknown as { getAllTools?: () => Array<{ name?: string; description?: string; parameters?: unknown }> }).getAllTools?.() ?? [];
     const tools = selected.size > 0 ? allTools.filter((t) => selected.has(t.name ?? "")) : allTools;
 
     let skillsText = "";
@@ -316,7 +317,10 @@ export default function usage(pi: ExtensionAPI) {
       providerTokens: lastPromptTokens || null,
       estimate: breakdown.attributed,
     });
-    return formatBreakdown(breakdown, reported);
+    // Break the "Tool definitions" row into its heaviest tools, biggest first,
+    // so a costly MCP server or a fat schema is nameable rather than a lump.
+    const taxLines = formatToolTax(tools);
+    return taxLines.length > 0 ? `${formatBreakdown(breakdown, reported)}\n\n${taxLines.join("\n")}` : formatBreakdown(breakdown, reported);
   }
 
   pi.registerCommand("usage", {

package/package.json

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

@@ -170,6 +170,62 @@ function foldEntries(entries: unknown[]): { conversation: number; toolResults: n
   return { conversation, toolResults, thinking };
 }
 
+/** One tool's share of the schema tax: its estimated token cost and where it came from. */
+export interface ToolTax {
+  name: string;
+  tokens: number;
+  /** "builtin/ext", or "mcp:<server>" for an MCP tool. */
+  source: string;
+}
+
+/** The server an MCP tool belongs to (mcp__<server>__<tool>), or null. */
+export function mcpServerOf(name: string): string | null {
+  const m = /^mcp__(.+?)__/.exec(name);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Every active tool ranked by the tokens its schema (name + description +
+ * parameters) adds to the prefix of every request. The "Tool definitions" row
+ * in the breakdown is this sum; this says which tools make it up, biggest
+ * first — the live, per-session answer to what @pify-adjacent "subagent-tax"
+ * measures across harnesses. Same chars/4 estimate as everything else here.
+ */
+export function toolTax(tools: BreakdownInput["tools"]): ToolTax[] {
+  return tools
+    .map((tool) => {
+      const name = String(tool.name ?? "");
+      const server = mcpServerOf(name);
+      return {
+        name,
+        tokens: estimateTextTokens({ name, description: tool.description, parameters: tool.parameters }),
+        source: server ? `mcp:${server}` : "builtin/ext",
+      };
+    })
+    .sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+}
+
+/** A compact "heaviest tool schemas" block: the top `max`, then a by-source subtotal. */
+export function formatToolTax(tools: BreakdownInput["tools"], max = 8): string[] {
+  const ranked = toolTax(tools);
+  if (ranked.length === 0) return [];
+  const total = ranked.reduce((sum, t) => sum + t.tokens, 0);
+  const width = Math.min(ranked.length, max) > 0 ? ranked.slice(0, max).reduce((m, t) => Math.max(m, t.name.length), 0) : 0;
+  const lines = [`Heaviest tool schemas (${ranked.length} ${ranked.length === 1 ? "tool" : "tools"}, ~${formatTokens(total)} of the prefix):`];
+  for (const t of ranked.slice(0, max)) {
+    lines.push(`  ${t.name.padEnd(width)}  ${formatTokens(t.tokens).padStart(6)}  ${t.source === "builtin/ext" ? "" : t.source}`.trimEnd());
+  }
+  if (ranked.length > max) {
+    const rest = ranked.slice(max).reduce((sum, t) => sum + t.tokens, 0);
+    lines.push(`  … and ${ranked.length - max} more, ~${formatTokens(rest)}`);
+  }
+  const bySource = new Map<string, number>();
+  for (const t of ranked) bySource.set(t.source, (bySource.get(t.source) ?? 0) + t.tokens);
+  const subtotals = [...bySource.entries()].sort((a, b) => b[1] - a[1]).map(([s, n]) => `${s} ~${formatTokens(n)}`);
+  if (subtotals.length > 1) lines.push(`  by source: ${subtotals.join(", ")}`);
+  return lines;
+}
+
 export function buildBreakdown(input: BreakdownInput): ContextBreakdown {
   const memory = input.contextFiles.reduce(
     (sum, file) => sum + embeddedTokens(input.systemPrompt, file.content ?? ""),