feat(tui/sidebar): accurate token-budget breakdown with Tool Definitions

Split the 'Conversation' slice into two honest categories so the
sidebar and status dialog show where the prompt budget is actually
going.

Problem
-------
On a fresh session the sidebar reported ~75K 'Conversation' on a
one-line user message. The 'Conversation' column was computed as
(input_tokens - system_tokens - injected_history_tokens) and was
labeled as user/assistant text — but most of the delta is actually
tool JSON schemas. An HTTP capture of a live Opus 4.7 request on a
long session confirmed:

  - system: ~16K
  - messages: ~148K (text + reasoning + tool calls + tool results)
  - tools:   ~23K  (40 tool definitions, biggest mcp_Bash at 2.7K)

Our previous estimator only counted 'text' parts, missing reasoning,
tool inputs, tool outputs, tool_result content, and images — which
pushed ~130K of real message content into the 'tools' remainder and
produced nonsense like '74K Tool Definitions' on a long session.

Fix
---
Persist a new `conversation_tokens` column (via ensureColumn, no
migration needed) and compute it at transform time by summing every
token-bearing field across the non-ignored parts we send on the
wire:

  - text / reasoning         : part.text
  - tool (OpenCode)          : state.input + state.output
  - tool-invocation          : args
  - tool_use                 : input
  - tool_result              : content
  - file (image/*)           : Anthropic (w*h)/750 formula

For images, added packages/plugin/src/hooks/magic-context/
image-token-estimate.ts that parses PNG IHDR, JPEG SOF0/SOF2,
WebP VP8/VP8L/VP8X, and GIF LSD headers directly from the
base64-decoded prefix (~128 bytes is enough for any of them), so
we match Anthropic's actual billed image tokens (1024x768 -> 1049,
2560x1440 -> 4915) instead of guessing 125K per screenshot from
base64 char count.

Display layer (RPC + sidebar + status dialog):

  - Conversation     = messagesBlockTokens
                        - compartmentTokens - factTokens - memoryTokens
  - Tool Definitions = inputTokens - systemPromptTokens - messagesBlockTokens

Both floors at 0. New 'Tool Definitions' label (not 'Tools' — that
reads like tool calls). Cached in session_meta so RPC/TUI reads are
synchronous.

Effect on the reported 175K session:

  - Before: System 17K / Compartments 63K / Facts 0 / Memories 6K /
            Conversation 16K / Tools 74K
  - After:  System 17K / Compartments 63K / Facts 0 / Memories 6K /
            Conversation ~123K / Tool Definitions ~36K

Residual ~13K overshoot on Tool Definitions vs the 23K true tools
size comes from our char/token heuristic (estimateTokens = len/4)
being looser than Anthropic's real tokenizer. A 75%+ accuracy
improvement without requiring a real tokenizer bundle.

Writes to session_meta are wrapped in a try/catch that swallows
SQLITE_BUSY (telemetry; next transform refreshes) and logs anything
else.

Tests
-----
- New image-token-estimate.test.ts covers PNG/JPEG/WebP/GIF decoding,
  malformed headers, tiny images, huge images.
- Full suite: 531 tests pass, typecheck clean.

Author: ualtinok

packages/plugin/src/features/magic-context/storage-db.ts

@@ -299,6 +299,11 @@ CREATE INDEX IF NOT EXISTS idx_dream_queue_pending ON dream_queue(started_at, en
     ensureColumn(db, "session_meta", "system_prompt_tokens", "INTEGER DEFAULT 0");
     ensureColumn(db, "session_meta", "compaction_marker_state", "TEXT DEFAULT ''");
     ensureColumn(db, "session_meta", "key_files", "TEXT DEFAULT ''");
+    // Token estimate of output.messages[] after transform manipulation. Used by
+    // the sidebar / dashboard to split inputTokens into Conversation vs Tools
+    // segments, since Anthropic's usage data rolls system + tools + messages
+    // together into cache.write but we want to attribute them separately.
+    ensureColumn(db, "session_meta", "conversation_tokens", "INTEGER DEFAULT 0");
 }
 
 // Intentional: the definition regex allows single quotes and parens because SQLite column

packages/plugin/src/features/magic-context/storage-meta-shared.ts

@@ -18,6 +18,7 @@ export interface SessionMetaRow {
     // for backward compatibility with pre-release DBs where the column was INTEGER.
     system_prompt_hash: string | number;
     system_prompt_tokens: number;
+    conversation_tokens: number;
     cleared_reasoning_through_tag: number;
 }
 
@@ -35,6 +36,7 @@ export const META_COLUMNS: Record<string, string> = {
     compartmentInProgress: "compartment_in_progress",
     systemPromptHash: "system_prompt_hash",
     systemPromptTokens: "system_prompt_tokens",
+    conversationTokens: "conversation_tokens",
     clearedReasoningThroughTag: "cleared_reasoning_through_tag",
 };
 
@@ -78,6 +80,7 @@ export function getDefaultSessionMeta(sessionId: string): SessionMeta {
         compartmentInProgress: false,
         systemPromptHash: "",
         systemPromptTokens: 0,
+        conversationTokens: 0,
         clearedReasoningThroughTag: 0,
     };
 }
@@ -125,6 +128,8 @@ export function toSessionMeta(row: SessionMetaRow): SessionMeta {
         compartmentInProgress: row.compartment_in_progress === 1,
         systemPromptHash: String(row.system_prompt_hash),
         systemPromptTokens: row.system_prompt_tokens,
+        conversationTokens:
+            typeof row.conversation_tokens === "number" ? row.conversation_tokens : 0,
         clearedReasoningThroughTag: row.cleared_reasoning_through_tag,
     };
 }

packages/plugin/src/features/magic-context/types.ts

@@ -34,6 +34,7 @@ export interface SessionMeta {
     compartmentInProgress: boolean;
     systemPromptHash: string;
     systemPromptTokens: number;
+    conversationTokens: number;
     clearedReasoningThroughTag: number;
 }
 

packages/plugin/src/hooks/magic-context/image-token-estimate.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { estimateImageTokensFromDataUrl } from "./image-token-estimate";
+
+function makePngDataUrl(width: number, height: number): string {
+    // Minimum valid PNG header + IHDR chunk with correct width/height.
+    // We don't need full chunks — our parser only reads offsets 16-23.
+    const buf = new Uint8Array(24);
+    // PNG magic
+    buf[0] = 0x89;
+    buf[1] = 0x50;
+    buf[2] = 0x4e;
+    buf[3] = 0x47;
+    buf[4] = 0x0d;
+    buf[5] = 0x0a;
+    buf[6] = 0x1a;
+    buf[7] = 0x0a;
+    // IHDR length placeholder (bytes 8-11) and type "IHDR" (12-15) — parser ignores these
+    buf[8] = 0;
+    buf[9] = 0;
+    buf[10] = 0;
+    buf[11] = 13;
+    buf[12] = 0x49;
+    buf[13] = 0x48;
+    buf[14] = 0x44;
+    buf[15] = 0x52;
+    // Width (16-19) big-endian
+    buf[16] = (width >>> 24) & 0xff;
+    buf[17] = (width >>> 16) & 0xff;
+    buf[18] = (width >>> 8) & 0xff;
+    buf[19] = width & 0xff;
+    // Height (20-23) big-endian
+    buf[20] = (height >>> 24) & 0xff;
+    buf[21] = (height >>> 16) & 0xff;
+    buf[22] = (height >>> 8) & 0xff;
+    buf[23] = height & 0xff;
+    const binary = Array.from(buf)
+        .map((b) => String.fromCharCode(b))
+        .join("");
+    return `data:image/png;base64,${btoa(binary)}`;
+}
+
+describe("estimateImageTokensFromDataUrl", () => {
+    test("PNG 1024x768 (typical screenshot)", () => {
+        // Formula: (1024 × 768) / 750 = 1048.58 → ceil = 1049
+        const tokens = estimateImageTokensFromDataUrl(makePngDataUrl(1024, 768));
+        expect(tokens).toBe(1049);
+    });
+
+    test("PNG 2560x1440 (retina screenshot)", () => {
+        // (2560 × 1440) / 750 = 4915.2 → ceil = 4916 → clamped to 4500
+        const tokens = estimateImageTokensFromDataUrl(makePngDataUrl(2560, 1440));
+        expect(tokens).toBe(4500);
+    });
+
+    test("PNG 400x300 (small image)", () => {
+        // (400 × 300) / 750 = 160
+        const tokens = estimateImageTokensFromDataUrl(makePngDataUrl(400, 300));
+        expect(tokens).toBe(160);
+    });
+
+    test("PNG 100x100 (tiny)", () => {
+        const tokens = estimateImageTokensFromDataUrl(makePngDataUrl(100, 100));
+        // (100 * 100) / 750 = 13.33 → ceil 14
+        expect(tokens).toBe(14);
+    });
+
+    test("falls back on unparseable data url", () => {
+        const tokens = estimateImageTokensFromDataUrl("data:image/png;base64,garbage");
+        expect(tokens).toBeGreaterThan(0);
+        expect(tokens).toBeLessThanOrEqual(4500);
+    });
+
+    test("falls back on missing comma", () => {
+        const tokens = estimateImageTokensFromDataUrl("data:image/png;base64garbage");
+        expect(tokens).toBeGreaterThan(0);
+    });
+});

packages/plugin/src/hooks/magic-context/image-token-estimate.ts

@@ -0,0 +1,170 @@
+// Image token estimation that matches Anthropic's vision billing formula.
+//
+// Anthropic vision docs: tokens ≈ (width × height) / 750
+// https://docs.claude.com/en/build-with-claude/vision
+//
+// Images are sent inline as data URLs. Base64 char length is a terrible proxy
+// (50x over-estimate for a typical screenshot), so we parse PNG/JPEG headers
+// directly to read real pixel dimensions.
+
+const IMAGE_TOKEN_DIVISOR = 750;
+const IMAGE_FALLBACK_TOKENS = 1200; // ~ 950×950 mid-size image
+const IMAGE_TOKEN_CAP = 4500; // Anthropic's max for a single image
+
+/**
+ * Estimate token cost of an image from its data URL.
+ * Returns a conservative fallback when parsing fails.
+ */
+export function estimateImageTokensFromDataUrl(url: string): number {
+    const comma = url.indexOf(",");
+    if (comma < 0) return IMAGE_FALLBACK_TOKENS;
+    const header = url.slice(0, comma);
+    const payload = url.slice(comma + 1);
+
+    // Only decode the first ~32 bytes of the image — enough for both PNG IHDR
+    // (bytes 16-24) and JPEG SOF markers (typically within first 256 bytes).
+    // Read up to ~512 bytes of base64 to cover edge-case JPEG marker offsets.
+    const sliceLen = Math.min(512, payload.length);
+    const preview = payload.slice(0, sliceLen);
+
+    let bytes: Uint8Array;
+    try {
+        bytes = base64Decode(preview);
+    } catch {
+        return IMAGE_FALLBACK_TOKENS;
+    }
+
+    if (header.includes("image/png")) {
+        const dims = parsePngDimensions(bytes);
+        if (dims) return clampImageTokens(Math.ceil((dims.w * dims.h) / IMAGE_TOKEN_DIVISOR));
+    } else if (header.includes("image/jpeg") || header.includes("image/jpg")) {
+        const dims = parseJpegDimensions(bytes);
+        if (dims) return clampImageTokens(Math.ceil((dims.w * dims.h) / IMAGE_TOKEN_DIVISOR));
+    } else if (header.includes("image/webp")) {
+        const dims = parseWebpDimensions(bytes);
+        if (dims) return clampImageTokens(Math.ceil((dims.w * dims.h) / IMAGE_TOKEN_DIVISOR));
+    } else if (header.includes("image/gif")) {
+        const dims = parseGifDimensions(bytes);
+        if (dims) return clampImageTokens(Math.ceil((dims.w * dims.h) / IMAGE_TOKEN_DIVISOR));
+    }
+
+    return IMAGE_FALLBACK_TOKENS;
+}
+
+function clampImageTokens(n: number): number {
+    if (n < 1) return 1;
+    if (n > IMAGE_TOKEN_CAP) return IMAGE_TOKEN_CAP;
+    return n;
+}
+
+function base64Decode(b64: string): Uint8Array {
+    // atob is available in Bun / Node 20+. Pad to multiple of 4.
+    const pad = b64.length % 4;
+    const padded = pad === 0 ? b64 : b64 + "=".repeat(4 - pad);
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+    return out;
+}
+
+// PNG: bytes 0-7 = magic; IHDR starts at byte 8; width = 16..19, height = 20..23 (big-endian).
+function parsePngDimensions(b: Uint8Array): { w: number; h: number } | null {
+    if (b.length < 24) return null;
+    if (
+        b[0] !== 0x89 ||
+        b[1] !== 0x50 ||
+        b[2] !== 0x4e ||
+        b[3] !== 0x47 ||
+        b[4] !== 0x0d ||
+        b[5] !== 0x0a ||
+        b[6] !== 0x1a ||
+        b[7] !== 0x0a
+    )
+        return null;
+    const w = readUint32BE(b, 16);
+    const h = readUint32BE(b, 20);
+    if (!w || !h) return null;
+    return { w, h };
+}
+
+// JPEG: scan for SOF markers (0xFFC0..0xFFC3, 0xFFC5..0xFFC7, 0xFFC9..0xFFCB, 0xFFCD..0xFFCF).
+// After marker: length (2 bytes), precision (1 byte), height (2 bytes), width (2 bytes).
+function parseJpegDimensions(b: Uint8Array): { w: number; h: number } | null {
+    if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8) return null;
+    let i = 2;
+    while (i < b.length - 8) {
+        if (b[i] !== 0xff) {
+            i++;
+            continue;
+        }
+        const marker = b[i + 1];
+        if (marker === undefined) break;
+        if (isSofMarker(marker)) {
+            // i+2: segment length (2B), i+4: precision (1B), i+5: height (2B), i+7: width (2B)
+            const h = (b[i + 5]! << 8) | b[i + 6]!;
+            const w = (b[i + 7]! << 8) | b[i + 8]!;
+            if (w && h) return { w, h };
+            return null;
+        }
+        // Skip over this segment. Marker has 2-byte length at i+2.
+        if (marker === 0xd8 || marker === 0xd9 || marker === 0x01) {
+            i += 2;
+            continue;
+        }
+        const segLen = (b[i + 2]! << 8) | b[i + 3]!;
+        if (segLen < 2) return null;
+        i += 2 + segLen;
+    }
+    return null;
+}
+
+function isSofMarker(m: number): boolean {
+    if (m >= 0xc0 && m <= 0xc3) return true;
+    if (m >= 0xc5 && m <= 0xc7) return true;
+    if (m >= 0xc9 && m <= 0xcb) return true;
+    if (m >= 0xcd && m <= 0xcf) return true;
+    return false;
+}
+
+// WebP: "RIFF....WEBPVP8[ L|X| ]" — different chunk layouts per variant.
+function parseWebpDimensions(b: Uint8Array): { w: number; h: number } | null {
+    if (b.length < 30) return null;
+    if (b[0] !== 0x52 || b[1] !== 0x49 || b[2] !== 0x46 || b[3] !== 0x46) return null; // RIFF
+    if (b[8] !== 0x57 || b[9] !== 0x45 || b[10] !== 0x42 || b[11] !== 0x50) return null; // WEBP
+    const variant = String.fromCharCode(b[12]!, b[13]!, b[14]!, b[15]!);
+    if (variant === "VP8 ") {
+        // Lossy: width/height at bytes 26-29 (14-bit each, little-endian)
+        const w = ((b[26]! | (b[27]! << 8)) & 0x3fff) || 0;
+        const h = ((b[28]! | (b[29]! << 8)) & 0x3fff) || 0;
+        if (w && h) return { w, h };
+    } else if (variant === "VP8L") {
+        // Lossless: 14-bit width/height starting byte 21
+        const b0 = b[21]!;
+        const b1 = b[22]!;
+        const b2 = b[23]!;
+        const b3 = b[24]!;
+        const w = 1 + ((b0 | (b1 << 8)) & 0x3fff);
+        const h = 1 + (((b1 >> 6) | (b2 << 2) | (b3 << 10)) & 0x3fff);
+        if (w && h) return { w, h };
+    } else if (variant === "VP8X") {
+        // Extended: width-1 at 24..26 (24-bit LE), height-1 at 27..29 (24-bit LE)
+        const w = 1 + (b[24]! | (b[25]! << 8) | (b[26]! << 16));
+        const h = 1 + (b[27]! | (b[28]! << 8) | (b[29]! << 16));
+        if (w && h) return { w, h };
+    }
+    return null;
+}
+
+// GIF: "GIF87a" or "GIF89a" then width (2B LE) + height (2B LE)
+function parseGifDimensions(b: Uint8Array): { w: number; h: number } | null {
+    if (b.length < 10) return null;
+    if (b[0] !== 0x47 || b[1] !== 0x49 || b[2] !== 0x46) return null;
+    const w = b[6]! | (b[7]! << 8);
+    const h = b[8]! | (b[9]! << 8);
+    if (!w || !h) return null;
+    return { w, h };
+}
+
+function readUint32BE(b: Uint8Array, offset: number): number {
+    return (b[offset]! << 24) | (b[offset + 1]! << 16) | (b[offset + 2]! << 8) | b[offset + 3]!;
+}