@juspay/neurolink 12.7.9 → 12.9.0

package/dist/cli/commands/usage.js

@@ -106,13 +106,22 @@ export class UsageCommandFactory {
         // block of zeros for it buries the rows that matter, so it gets one line.
         const quiet = rows.filter(([, t]) => t && t.requests === 0);
         const active = rows.filter(([, t]) => t && t.requests > 0);
+        // What `requests` counts is not the same for every reader, so the label is
+        // read off the descriptor rather than hard-coded. Printing "turns" for a
+        // reader that counts sessions is a small lie that makes a Cursor row look
+        // directly comparable to a Claude Code row, which it is not.
+        const unitById = new Map(getLocalUsageDescriptors().map((d) => [d.id, d.requestUnit ?? "turn"]));
         for (const [cliId, totals] of active) {
             if (!totals) {
                 continue;
             }
             const cached = totals.cacheReadTokens + totals.cacheCreationTokens;
             logger.always(chalk.cyan(`  ${cliId}`));
-            logger.always(`    turns   ${UsageCommandFactory.formatTokens(totals.requests)}`);
+            const unit = unitById.get(cliId) ?? "turn";
+            logger.always(unit === "session-snapshot"
+                ? `    sessions ${UsageCommandFactory.formatTokens(totals.requests)}` +
+                    chalk.dim("   (context snapshots, not per-turn usage)")
+                : `    turns   ${UsageCommandFactory.formatTokens(totals.requests)}`);
             logger.always(`    input   ${UsageCommandFactory.formatTokens(totals.inputTokens)}` +
                 `    output ${UsageCommandFactory.formatTokens(totals.outputTokens)}` +
                 `    cached ${UsageCommandFactory.formatTokens(cached)}`);

package/dist/localUsage/cursorReader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Reads token usage out of Cursor CLI's local chat store.
+ *
+ * Store: `~/.cursor/chats/<workspaceHash>/<agentId>/store.db`, one SQLite file
+ * per agent session, with two tables:
+ *
+ *   - `meta`  — a single row whose `value` is **hex-encoded** JSON (not JSON,
+ *     and not a blob: a hex *string*), carrying `latestRootBlobId`, `name`,
+ *     `createdAt` and `lastUsedModel`.
+ *   - `blobs` — a content-addressed store, `id` = SHA-256 of `data`. Some
+ *     blobs are UTF-8 JSON messages; the root blob is **protobuf**.
+ *
+ * **What this reader reports is NOT cumulative spend, and that difference is
+ * the whole reason to read this file before trusting the number.** Every other
+ * reader here sums per-turn usage across a transcript. Cursor persists no
+ * per-turn usage at all: the only counts in the store are a snapshot of the
+ * *current context composition* on the newest root blob — how many tokens the
+ * system prompt, tools, rules, skills, subagents and conversation each occupy
+ * right now. A session with 200 turns and a session with 1 turn produce one
+ * snapshot each. Summing across sessions therefore answers "how much context
+ * was loaded, last time each session was touched", never "how much was billed".
+ * It lands in `inputTokens` because context is what gets sent as input, and it
+ * is the honest home for it — but a dashboard adding this to a metered CLI's
+ * input tokens is adding two different quantities. The same hazard OpenCode's
+ * reader documents for double-counted proxy traffic, one step further.
+ *
+ * **Why the parse validates itself.** Protobuf field numbers are an internal
+ * detail of a closed-source binary that updates itself, so hard-coding "the
+ * total is field 5.1" is a claim about a format nobody published. Instead the
+ * parser finds the breakdown by *shape* — submessages of exactly
+ * `{1: string, 2: string, 3?: varint, 4?: varint}` — sums their token fields,
+ * and then requires that sum to appear verbatim as a varint elsewhere in the
+ * same message. On the reference store that is
+ * 480 + 11592 + 9257 + 6621 + 391 + 143 = 28484, matching the stored 28484
+ * exactly, against a 200000 window. If a future Cursor renumbers its fields the
+ * shape match still works; if it changes the *structure*, the sum stops
+ * matching and the session is reported as an error rather than counted wrong.
+ * A reader that cannot tell "I parsed nothing" from "this session used nothing"
+ * is the failure this check exists to prevent.
+ *
+ * Cost is `unavailable`, not zero-with-confidence: Cursor is a subscription and
+ * the store records no model-priced turns to derive a figure from.
+ */
+import type { LocalUsageReader } from "../types/index.js";
+/**
+ * @returns the session's context-token total, or `null` when the blob holds no
+ * breakdown whose entries sum to a total stated alongside them.
+ */
+export declare function extractCursorContextTokens(rootBlob: Uint8Array): number | null;
+export declare function createCursorReader(): Promise<LocalUsageReader>;

package/dist/localUsage/cursorReader.js

@@ -0,0 +1,450 @@
+/**
+ * Reads token usage out of Cursor CLI's local chat store.
+ *
+ * Store: `~/.cursor/chats/<workspaceHash>/<agentId>/store.db`, one SQLite file
+ * per agent session, with two tables:
+ *
+ *   - `meta`  — a single row whose `value` is **hex-encoded** JSON (not JSON,
+ *     and not a blob: a hex *string*), carrying `latestRootBlobId`, `name`,
+ *     `createdAt` and `lastUsedModel`.
+ *   - `blobs` — a content-addressed store, `id` = SHA-256 of `data`. Some
+ *     blobs are UTF-8 JSON messages; the root blob is **protobuf**.
+ *
+ * **What this reader reports is NOT cumulative spend, and that difference is
+ * the whole reason to read this file before trusting the number.** Every other
+ * reader here sums per-turn usage across a transcript. Cursor persists no
+ * per-turn usage at all: the only counts in the store are a snapshot of the
+ * *current context composition* on the newest root blob — how many tokens the
+ * system prompt, tools, rules, skills, subagents and conversation each occupy
+ * right now. A session with 200 turns and a session with 1 turn produce one
+ * snapshot each. Summing across sessions therefore answers "how much context
+ * was loaded, last time each session was touched", never "how much was billed".
+ * It lands in `inputTokens` because context is what gets sent as input, and it
+ * is the honest home for it — but a dashboard adding this to a metered CLI's
+ * input tokens is adding two different quantities. The same hazard OpenCode's
+ * reader documents for double-counted proxy traffic, one step further.
+ *
+ * **Why the parse validates itself.** Protobuf field numbers are an internal
+ * detail of a closed-source binary that updates itself, so hard-coding "the
+ * total is field 5.1" is a claim about a format nobody published. Instead the
+ * parser finds the breakdown by *shape* — submessages of exactly
+ * `{1: string, 2: string, 3?: varint, 4?: varint}` — sums their token fields,
+ * and then requires that sum to appear verbatim as a varint elsewhere in the
+ * same message. On the reference store that is
+ * 480 + 11592 + 9257 + 6621 + 391 + 143 = 28484, matching the stored 28484
+ * exactly, against a 200000 window. If a future Cursor renumbers its fields the
+ * shape match still works; if it changes the *structure*, the sum stops
+ * matching and the session is reported as an error rather than counted wrong.
+ * A reader that cannot tell "I parsed nothing" from "this session used nothing"
+ * is the failure this check exists to prevent.
+ *
+ * Cost is `unavailable`, not zero-with-confidence: Cursor is a subscription and
+ * the store records no model-priced turns to derive a figure from.
+ */
+import { readdir, stat } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { resolveScanCutoffMs } from "./scanWindow.js";
+const CLI_ID = "cursor";
+function chatsRoot() {
+    return join(homedir(), ".cursor", "chats");
+}
+function emptyTotals() {
+    return {
+        requests: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        costUsd: 0,
+        costConfidence: "unavailable",
+        unpricedRequests: 0,
+        unpricedModels: [],
+    };
+}
+/**
+ * Decode one protobuf message into its top-level fields.
+ *
+ * Returns `null` rather than throwing on anything malformed — this walks blobs
+ * from a third-party binary, so "not the shape I expected" is an ordinary
+ * outcome and must not abort a scan of the other sessions.
+ */
+function decodeMessage(buf) {
+    const out = [];
+    let i = 0;
+    const varint = () => {
+        let result = 0;
+        let shift = 0;
+        while (i < buf.length) {
+            // Read then advance, without a non-null assertion: the loop condition
+            // makes this in-bounds, but an assertion would keep being true if the
+            // condition ever changed, and this parser's whole job is to distrust the
+            // bytes it is handed.
+            const byte = buf[i];
+            i += 1;
+            if (byte === undefined) {
+                return null;
+            }
+            // Beyond 2^53 a JS number stops being exact, and a token count that
+            // silently loses precision is worse than a refused parse.
+            if (shift > 53) {
+                return null;
+            }
+            result += (byte & 0x7f) * Math.pow(2, shift);
+            shift += 7;
+            if ((byte & 0x80) === 0) {
+                return result;
+            }
+        }
+        return null;
+    };
+    while (i < buf.length) {
+        const key = varint();
+        if (key === null) {
+            return null;
+        }
+        const field = Math.floor(key / 8);
+        const wireType = key % 8;
+        if (wireType === 0) {
+            const value = varint();
+            if (value === null) {
+                return null;
+            }
+            out.push({ field, kind: "varint", value });
+        }
+        else if (wireType === 2) {
+            const length = varint();
+            if (length === null || i + length > buf.length) {
+                return null;
+            }
+            out.push({ field, kind: "bytes", value: buf.subarray(i, i + length) });
+            i += length;
+        }
+        else if (wireType === 5) {
+            i += 4;
+        }
+        else if (wireType === 1) {
+            i += 8;
+        }
+        else {
+            // Groups (3/4) are deprecated and absent here; anything else is garbage.
+            return null;
+        }
+        if (i > buf.length) {
+            return null;
+        }
+    }
+    return out;
+}
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Match one breakdown entry by shape.
+ *
+ * Deliberately strict — every field must be one of the four expected numbers
+ * with the expected wire type, and fields 1 and 2 must be valid UTF-8. A loose
+ * matcher would collect unrelated submessages and inflate the sum, and the sum
+ * is the only thing proving the parse found the right structure at all.
+ */
+function tryParsePart(buf) {
+    const fields = decodeMessage(buf);
+    if (fields === null || fields.length === 0) {
+        return null;
+    }
+    let name;
+    let sawLabel = false;
+    let tokens = 0;
+    for (const f of fields) {
+        if (f.field === 1 && f.kind === "bytes") {
+            try {
+                name = utf8.decode(f.value);
+            }
+            catch {
+                return null;
+            }
+        }
+        else if (f.field === 2 && f.kind === "bytes") {
+            try {
+                utf8.decode(f.value);
+                sawLabel = true;
+            }
+            catch {
+                return null;
+            }
+        }
+        else if (f.field === 3 && f.kind === "varint") {
+            tokens = f.value;
+        }
+        else if (f.field === 4 && f.kind === "varint") {
+            // Character count; read but not reported — it is the denominator behind
+            // the ~4.08 chars/token ratio, not a usage figure.
+        }
+        else {
+            return null;
+        }
+    }
+    if (name === undefined || !sawLabel) {
+        return null;
+    }
+    return { name, tokens };
+}
+/**
+ * Find a breakdown CONTAINER: one message that both holds the entries and
+ * states their total.
+ *
+ * The first version of this searched the whole tree — every shape-matching
+ * submessage anywhere became a "part", and the total merely had to appear as
+ * some varint somewhere. Both halves were too loose, and the real data proves
+ * it rather than hypothesis: this machine's own root blob carries a field 21
+ * of `{1: "/Users/…/feat/support-for-ide", 2: "feat/support-for-ide"}`, which
+ * is a workspace descriptor and matches the entry shape exactly. Today it is
+ * harmless only because it has no field 3, so it contributes 0. Give it one —
+ * an entirely ordinary thing for a protobuf message to grow — and the sum
+ * inflates; and because a 643-byte blob already holds seventeen distinct
+ * varints, "does the sum equal ANY varint in the tree" is a coincidence
+ * waiting to be satisfied. The result would be a wrong number that had passed
+ * its own validation, which is worse than no number at all.
+ *
+ * Scoping to a container closes both halves. The entries must be siblings
+ * inside one message, and that same message must carry their sum as one of its
+ * own varints — which is exactly how Cursor lays it out: the inner message
+ * holds the total at field 1, the window at field 2, and the entries as a
+ * repeated field 3. A lone shape-match like field 21 can never qualify: it has
+ * no varint fields at all, and no entry-shaped children.
+ *
+ * @returns the container's stated total, or `null` if no message in the tree
+ * both contains at least two entries and states their sum.
+ */
+function findBreakdownTotal(buf, depth) {
+    if (depth > 12) {
+        return null;
+    }
+    const fields = decodeMessage(buf);
+    if (fields === null) {
+        return null;
+    }
+    const parts = [];
+    for (const f of fields) {
+        if (f.kind === "bytes") {
+            const part = tryParsePart(f.value);
+            if (part !== null) {
+                parts.push(part);
+            }
+        }
+    }
+    // Two, not one: a single match is far likelier to be an unrelated two-string
+    // message than a context breakdown. Safe because Cursor writes its breakdown
+    // as a FIXED set — system_prompt, tools, rules, skills, mcp, subagents,
+    // summarized_conversation, conversation — all eight present even when a
+    // category is empty (mcp and summarized_conversation carried no token field
+    // at all on the reference blob). So the count never drops toward one as a
+    // session shrinks; a one-entry container would mean the format changed, and
+    // that is a case to refuse rather than guess at.
+    if (parts.length >= 2) {
+        const sum = parts.reduce((acc, p) => acc + p.tokens, 0);
+        if (sum > 0) {
+            for (const f of fields) {
+                if (f.kind === "varint" && f.value === sum) {
+                    return sum;
+                }
+            }
+        }
+    }
+    // Not this message — recurse. Depth-first, so a nested container is still
+    // found when its parent also holds shape-matching noise.
+    for (const f of fields) {
+        if (f.kind !== "bytes") {
+            continue;
+        }
+        const found = findBreakdownTotal(f.value, depth + 1);
+        if (found !== null) {
+            return found;
+        }
+    }
+    return null;
+}
+/**
+ * @returns the session's context-token total, or `null` when the blob holds no
+ * breakdown whose entries sum to a total stated alongside them.
+ */
+export function extractCursorContextTokens(rootBlob) {
+    return findBreakdownTotal(rootBlob, 0);
+}
+/** `~/.cursor/chats/<workspaceHash>/<agentId>/store.db`, two levels down. */
+async function findStoreDatabases() {
+    const root = chatsRoot();
+    const found = [];
+    let workspaces;
+    try {
+        workspaces = await readdir(root);
+    }
+    catch {
+        return found;
+    }
+    for (const workspace of workspaces) {
+        let agents;
+        try {
+            agents = await readdir(join(root, workspace));
+        }
+        catch {
+            continue;
+        }
+        for (const agent of agents) {
+            const dbPath = join(root, workspace, agent, "store.db");
+            try {
+                const info = await stat(dbPath);
+                if (info.isFile()) {
+                    found.push(dbPath);
+                }
+            }
+            catch {
+                // Not every directory is an agent session.
+            }
+        }
+    }
+    return found;
+}
+export async function createCursorReader() {
+    return {
+        descriptor: {
+            id: CLI_ID,
+            displayName: "Cursor",
+            verified: true,
+            // Only the newest root blob per session carries a breakdown; earlier
+            // roots in the content-addressed chain hold none. Taking the latest is
+            // not a choice between duplicates, it is the only record that exists.
+            dedupStrategy: "last-write-wins",
+            costConfidence: "unavailable",
+            requiresSqlite: true,
+            requestUnit: "session-snapshot",
+        },
+        detect: async () => {
+            try {
+                const info = await stat(chatsRoot());
+                return info.isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+        scan: async (options) => {
+            const totals = emptyTotals();
+            const errors = [];
+            let DatabaseSync;
+            try {
+                const sqlite = await import("node:sqlite");
+                if (typeof sqlite === "object" &&
+                    sqlite !== null &&
+                    "DatabaseSync" in sqlite &&
+                    typeof sqlite.DatabaseSync ===
+                        "function") {
+                    DatabaseSync = sqlite.DatabaseSync;
+                }
+            }
+            catch (error) {
+                errors.push({
+                    cliId: CLI_ID,
+                    filePath: chatsRoot(),
+                    message: `node:sqlite unavailable on this runtime: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                return { cliId: CLI_ID, totals, filesScanned: 0, errors };
+            }
+            if (!DatabaseSync) {
+                errors.push({
+                    cliId: CLI_ID,
+                    filePath: chatsRoot(),
+                    message: "node:sqlite did not expose a callable DatabaseSync — the experimental API has likely changed shape",
+                });
+                return { cliId: CLI_ID, totals, filesScanned: 0, errors };
+            }
+            const cutoffMs = resolveScanCutoffMs(options?.sinceDays);
+            let filesScanned = 0;
+            for (const dbPath of await findStoreDatabases()) {
+                // Filter on the file, before opening it. Unlike OpenCode there is no
+                // per-row timestamp to filter in SQL: one database IS one session.
+                if (cutoffMs !== undefined) {
+                    try {
+                        const info = await stat(dbPath);
+                        if (info.mtimeMs < cutoffMs) {
+                            continue;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                let db;
+                try {
+                    // Read-only: Cursor may be running against this very file.
+                    db = new DatabaseSync(dbPath, { readOnly: true });
+                    filesScanned += 1;
+                    const metaRows = db.prepare("SELECT value FROM meta").all();
+                    const rawMeta = metaRows.find((row) => typeof row.value === "string")?.value;
+                    if (rawMeta === undefined) {
+                        continue;
+                    }
+                    // Hex-encoded JSON. Validated rather than assumed: a non-hex value
+                    // decodes to mojibake and would throw inside JSON.parse anyway, but
+                    // the explicit test says why the buffer conversion is there.
+                    if (!/^(?:[0-9a-fA-F]{2})+$/.test(rawMeta)) {
+                        continue;
+                    }
+                    let latestRootBlobId;
+                    try {
+                        const meta = JSON.parse(Buffer.from(rawMeta, "hex").toString("utf8"));
+                        if (typeof meta === "object" &&
+                            meta !== null &&
+                            "latestRootBlobId" in meta &&
+                            typeof meta
+                                .latestRootBlobId === "string") {
+                            latestRootBlobId = meta
+                                .latestRootBlobId;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (latestRootBlobId === undefined) {
+                        continue;
+                    }
+                    const blobRows = db
+                        .prepare("SELECT data FROM blobs WHERE id = ?")
+                        .all(latestRootBlobId);
+                    const blob = blobRows[0]?.data;
+                    if (!(blob instanceof Uint8Array) || blob.length === 0) {
+                        continue;
+                    }
+                    const contextTokens = extractCursorContextTokens(blob);
+                    if (contextTokens === null) {
+                        // Reported, never silently skipped: "no breakdown found" and "this
+                        // session used nothing" are different facts and must not collapse.
+                        errors.push({
+                            cliId: CLI_ID,
+                            filePath: dbPath,
+                            message: "root blob carried no context breakdown whose parts sum to a stated total — Cursor's on-disk format has likely changed",
+                        });
+                        continue;
+                    }
+                    // One snapshot per session, not one per turn. See this module's note.
+                    totals.requests += 1;
+                    totals.inputTokens += contextTokens;
+                }
+                catch (error) {
+                    errors.push({
+                        cliId: CLI_ID,
+                        filePath: dbPath,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                finally {
+                    try {
+                        db?.close();
+                    }
+                    catch {
+                        // Closing a database that failed to open is not a second failure.
+                    }
+                }
+            }
+            return { cliId: CLI_ID, totals, filesScanned, errors };
+        },
+    };
+}

package/dist/localUsage/grokReader.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reads token usage out of Grok Build's own session streams.
+ *
+ * Grok Build is xAI's official terminal coding agent (github.com/xai-org/
+ * grok-build, Rust, installed from x.ai/cli/install.sh as `grok`). An earlier
+ * note in this folder said "grok" named no product, only eight competing npm
+ * packages; it had searched npm for a Rust binary that is not distributed
+ * there, and is retracted here.
+ *
+ * Layout, confirmed by running the real binary against a redirected home:
+ * `$GROK_HOME/sessions/<url-encoded cwd>/<session-id>/`, defaulting to
+ * `~/.grok`. Each session directory holds `updates.jsonl` — the CLI's own
+ * documentation calls it the authoritative conversation log — plus
+ * `summary.json`, `chat_history.jsonl`, `signals.json` and others. The walk
+ * here reads exactly `<group>/<session>/updates.jsonl` and nothing deeper:
+ * a session directory can also hold `compaction_checkpoints/`, and a
+ * checkpoint that snapshots the stream would otherwise be counted twice.
+ *
+ * Each line is a JSON-RPC style record. The ones that matter are
+ * `method: "_x.ai/session/update"` with `params.update.sessionUpdate ===
+ * "turn_completed"`; a completed turn that reached a model carries a `usage`
+ * object with `inputTokens`, `outputTokens`, `cachedReadTokens`,
+ * `cacheCreationTokens`, `reasoningTokens`, `modelCalls`, a per-model
+ * `modelUsage` map and `numTurns`. A turn that failed before any model call
+ * carries no `usage` at all, so it excludes itself. `stop_reason` is not an
+ * eligibility test: a truncated or interrupted turn with a usage object was
+ * still billed.
+ *
+ * What the numbers MEAN took a second real turn to settle, and the answer is
+ * neither "per turn" nor "cumulative" but both, by process:
+ *
+ *   turn 1 (fresh process)      inputTokens 10141   numTurns 1
+ *   turn 2 (`grok -r`, new one) inputTokens 11034   numTurns 1
+ *
+ * The second record is not 21175, so the usage is not a session-lifetime
+ * counter. But the CLI's own persistence code says the figure is the
+ * process's live ledger, and computes a turn's cost as live minus the
+ * previous live value when the ledger has only grown — a running total within
+ * one process, reset when a new process resumes the session. A reader has no
+ * process boundary to look at; what it has is `numTurns`, the ledger's own
+ * turn counter. Strictly increasing, with every bucket at least as large,
+ * means the same ledger, and the turn's usage is the difference from the
+ * previous record. Anything else means a fresh ledger, and the whole record
+ * counts. Both real records above have numTurns 1, so both count whole, which
+ * is the measured truth. The in-process cumulative branch is taken from the
+ * CLI's source, not from a measurement — headless `-p` runs are one prompt
+ * per process, so no real stream on this machine exercises it.
+ *
+ * Duplicates: a prompt's terminal record can be re-emitted (the persistence
+ * layer folds a late re-emission into the same turn). Dedup is by
+ * `prompt_id`, scoped to the session directory — prompt ids are not
+ * documented as globally unique — keeping the last record seen. A record
+ * with no prompt id is keyed by its line.
+ *
+ * Cost is `unavailable`: the turn record carries no price, and Grok Build is
+ * a subscription product whose custom-model configurations can point at any
+ * OpenAI- or Anthropic-compatible endpoint — the real run here used DeepSeek.
+ * Cache and reasoning counts are reported as stored; every real sample so far
+ * has them at zero, so whether `cachedReadTokens` is a subset of
+ * `inputTokens` has not been measured and nothing is subtracted or folded
+ * until it has. Reasoning tokens in particular are NOT added to output: on the
+ * OpenAI wire they are a subset of completion tokens, and adding them would
+ * double count.
+ *
+ * Not read: the newer per-session `usage.json` the CLI writes from the same
+ * ledger. No real run on this machine produced one — the 1.0.13 binary's
+ * `grok usage` reports "No usage recorded" for these sessions — and a reader
+ * written against a struct definition alone is the guessed-format failure
+ * this folder keeps paying for. When a real file exists it belongs here as a
+ * fallback for a session with no readable stream, never as an addition.
+ */
+import type { LocalUsageReader } from "../types/index.js";
+export declare function createGrokReader(): Promise<LocalUsageReader>;