@juspay/neurolink 12.7.9 → 12.9.0

package/dist/localUsage/hermesReader.js

@@ -0,0 +1,350 @@
+/**
+ * Reads token usage out of Hermes Agent's SQLite state store.
+ *
+ * Hermes Agent is Nous Research's official CLI agent (github.com/NousResearch/
+ * hermes-agent), a Python program installed from its own install script — not
+ * an npm package. An earlier note in this folder said the opposite ("no
+ * official CLI, only an unofficial npm bridge"); it had searched npm for a
+ * product that is not distributed there, and is retracted here.
+ *
+ * Store: `$HERMES_HOME/state.db`, defaulting to `~/.hermes/state.db`, plus one
+ * `state.db` per profile under `profiles/<name>/`. SQLite, `schema_version`
+ * table (26 when this was written; `PRAGMA user_version` stays 0, so it is
+ * not the version to read). Confirmed on a real store produced by running the
+ * CLI itself, not inferred from documentation.
+ *
+ * Two tables carry usage, and they are NOT additive:
+ *
+ *   sessions            one row per session, with cumulative token columns
+ *                       for the PRIMARY task only.
+ *   session_model_usage one row per (session, model, billing, task), each
+ *                       with its own `api_call_count`, token columns and cost.
+ *
+ * Measured on the real store: a one-prompt session held a `sessions` row of
+ * 10,568 input / 1 output / 1 call, and TWO usage rows — the primary task
+ * (`task = ''`, identical numbers) and a `title_generation` task of 248 / 8 /
+ * 1 call that the `sessions` aggregate does not include. The usage rows are
+ * therefore the complete record of what Hermes actually sent to a provider,
+ * and this reader sums them. The `sessions` aggregate is read only for a
+ * session that has no usage rows at all (a store older than the migration
+ * that introduced the table), and never in addition to them.
+ *
+ * Cost: Hermes records `estimated_cost_usd` with a `cost_status` of
+ * `estimated`, from its own pricing snapshot. That is a modeled figure and is
+ * reported as such. `actual_cost_usd` is `NOT NULL DEFAULT 0` on usage rows,
+ * so a zero there is a schema default, not evidence of a free call — it is
+ * used only when `cost_status` explicitly says the figure is actual. A row
+ * with no trustworthy cost is counted as unpriced and its model named.
+ *
+ * Cache and reasoning columns are reported as stored. Every real sample so far
+ * has them at zero, so whether `cache_read_tokens` is a subset of
+ * `input_tokens` (OpenAI convention) or disjoint from it (Anthropic
+ * convention) has not been measured, and no subtraction or folding is applied
+ * until it has. Reasoning tokens are not added to output for the same reason.
+ *
+ * The time window is a snapshot filter, not an attribution: every row is a
+ * cumulative counter, so a session that spans the cutoff is either included
+ * whole or excluded whole, keyed on its last activity. Timestamps are epoch
+ * SECONDS stored as REAL.
+ */
+import { readdir, stat } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { resolveScanCutoffMs } from "./scanWindow.js";
+const CLI_ID = "hermes";
+function hermesHome() {
+    const env = process.env.HERMES_HOME;
+    return env !== undefined && env.trim().length > 0
+        ? env
+        : join(homedir(), ".hermes");
+}
+function emptyTotals() {
+    return {
+        requests: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        costUsd: 0,
+        costConfidence: "modeled",
+        unpricedRequests: 0,
+        unpricedModels: [],
+    };
+}
+/** A finite, non-negative number, or 0. NULL and garbage both read as 0. */
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : 0;
+}
+/** A finite, non-negative number, or null — for costs, where 0 is a value. */
+function amount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+}
+/** The root store plus one per profile. Missing pieces are simply absent. */
+async function findStateDatabases() {
+    const root = hermesHome();
+    const out = [];
+    const rootDb = join(root, "state.db");
+    try {
+        if ((await stat(rootDb)).isFile()) {
+            out.push(rootDb);
+        }
+    }
+    catch {
+        // No root store.
+    }
+    let profiles;
+    try {
+        profiles = (await readdir(join(root, "profiles"), { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return out;
+    }
+    for (const name of profiles) {
+        const db = join(root, "profiles", name, "state.db");
+        try {
+            if ((await stat(db)).isFile()) {
+                out.push(db);
+            }
+        }
+        catch {
+            // Profile without a store yet.
+        }
+    }
+    return out;
+}
+function columnsOf(db, table) {
+    // PRAGMA table_info cannot take a bound parameter; the table names here are
+    // fixed identifiers, never user input.
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return new Set(rows
+        .map((row) => row.name)
+        .filter((name) => typeof name === "string"));
+}
+const USAGE_REQUIRED = [
+    "session_id",
+    "model",
+    "api_call_count",
+    "input_tokens",
+    "output_tokens",
+];
+const SESSIONS_REQUIRED = [
+    "id",
+    "started_at",
+    "input_tokens",
+    "output_tokens",
+];
+const OPTIONAL_COUNTS = [
+    "cache_read_tokens",
+    "cache_write_tokens",
+    "reasoning_tokens",
+];
+const OPTIONAL_COST = [
+    "estimated_cost_usd",
+    "actual_cost_usd",
+    "cost_status",
+];
+/** `col` if the table has it, else a typed default under the same alias. */
+function select(have, col, fallback, alias = col) {
+    return have.has(col)
+        ? `${alias === col ? col : `${col} AS ${alias}`}`
+        : `${fallback} AS ${alias}`;
+}
+/**
+ * Which cost a row is allowed to claim.
+ *
+ * `cost_status` is provenance, and it governs which column is trusted: an
+ * explicit actual/billed status admits `actual_cost_usd`; an explicit
+ * estimated status admits `estimated_cost_usd`. Without a status, a POSITIVE
+ * estimate is still a computed value rather than a schema default and is
+ * accepted; a bare zero is not, because `actual_cost_usd` defaults to 0 on
+ * every usage row and would otherwise price every call at nothing.
+ */
+function rowCost(row) {
+    const status = typeof row.cost_status === "string" ? row.cost_status.toLowerCase() : "";
+    const actual = amount(row.actual_cost_usd);
+    const estimated = amount(row.estimated_cost_usd);
+    if (status === "actual" || status === "billed") {
+        return actual;
+    }
+    if (status === "estimated") {
+        return estimated;
+    }
+    return estimated !== null && estimated > 0 ? estimated : null;
+}
+/**
+ * `COALESCE` over the timestamp columns a schema actually has. SQLite rejects
+ * a one-argument COALESCE outright, and a minimal schema (or a fixture
+ * modelled on one) can have exactly one — `started_at` is the only required
+ * timestamp — so a single column is emitted bare.
+ */
+function newestOf(cols) {
+    const [only] = cols;
+    return cols.length === 1 && only !== undefined
+        ? only
+        : `COALESCE(${cols.join(", ")})`;
+}
+function foldRow(row, totals, unpriced) {
+    const calls = count(row.api_call_count);
+    const input = count(row.input_tokens);
+    const output = count(row.output_tokens);
+    if (calls === 0 && input + output === 0) {
+        // A failed one-shot leaves a session with no calls and no tokens. It is
+        // not usage, and counting it as a zero-token request would inflate the
+        // request count with attempts that never reached a model.
+        return;
+    }
+    totals.requests += calls > 0 ? calls : 1;
+    totals.inputTokens += input;
+    totals.outputTokens += output;
+    totals.cacheReadTokens += count(row.cache_read_tokens);
+    totals.cacheCreationTokens += count(row.cache_write_tokens);
+    const cost = rowCost(row);
+    if (cost === null) {
+        totals.unpricedRequests += calls > 0 ? calls : 1;
+        unpriced.add(typeof row.model === "string" && row.model ? row.model : "unknown");
+    }
+    else {
+        totals.costUsd += cost;
+    }
+}
+function readStore(db, dbPath, cutoffSeconds, totals, unpriced, errors) {
+    const sessionCols = columnsOf(db, "sessions");
+    if (sessionCols.size === 0) {
+        errors.push({
+            cliId: CLI_ID,
+            filePath: dbPath,
+            message: "no sessions table — not a Hermes state store, or one this reader does not understand",
+        });
+        return;
+    }
+    const missingSessions = SESSIONS_REQUIRED.filter((c) => !sessionCols.has(c));
+    if (missingSessions.length > 0) {
+        // Fail closed. Reading a partial schema and reporting a clean zero would
+        // look like "no usage" when the truth is "unreadable".
+        errors.push({
+            cliId: CLI_ID,
+            filePath: dbPath,
+            message: `sessions table lacks required column(s) ${missingSessions.join(", ")} — Hermes' schema has changed`,
+        });
+        return;
+    }
+    const usageCols = columnsOf(db, "session_model_usage");
+    const hasUsage = usageCols.size > 0 && USAGE_REQUIRED.every((c) => usageCols.has(c));
+    // Last activity, in seconds. Sessions know theirs; usage rows fall back to
+    // their session's when they carry no `last_seen` of their own.
+    const sessionAt = [
+        sessionCols.has("last_activity_at") ? "s.last_activity_at" : null,
+        sessionCols.has("ended_at") ? "s.ended_at" : null,
+        "s.started_at",
+    ].filter((c) => c !== null);
+    if (hasUsage) {
+        const at = [
+            usageCols.has("last_seen") ? "u.last_seen" : null,
+            usageCols.has("first_seen") ? "u.first_seen" : null,
+            ...sessionAt,
+        ].filter((c) => c !== null);
+        const sql = `SELECT u.session_id, u.model, u.api_call_count, u.input_tokens, u.output_tokens, ${OPTIONAL_COUNTS.map((c) => (usageCols.has(c) ? `u.${c}` : `0 AS ${c}`)).join(", ")}, ${OPTIONAL_COST.map((c) => usageCols.has(c) ? `u.${c}` : `NULL AS ${c}`).join(", ")}, ${newestOf(at)} AS at FROM session_model_usage u LEFT JOIN sessions s ON s.id = u.session_id`;
+        const rows = db.prepare(sql).all();
+        for (const row of rows) {
+            if (cutoffSeconds !== undefined && count(row.at) < cutoffSeconds) {
+                continue;
+            }
+            foldRow(row, totals, unpriced);
+        }
+    }
+    // Sessions with no usage rows: only the aggregate exists for them.
+    const orphanFilter = hasUsage
+        ? " WHERE NOT EXISTS (SELECT 1 FROM session_model_usage u WHERE u.session_id = s.id)"
+        : "";
+    const sessionSql = `SELECT s.id AS session_id, ${select(sessionCols, "model", "NULL")}, ${select(sessionCols, "api_call_count", "0")}, s.input_tokens, s.output_tokens, ${OPTIONAL_COUNTS.map((c) => sessionCols.has(c) ? `s.${c}` : `0 AS ${c}`).join(", ")}, ${OPTIONAL_COST.map((c) => sessionCols.has(c) ? `s.${c}` : `NULL AS ${c}`).join(", ")}, ${newestOf(sessionAt)} AS at FROM sessions s${orphanFilter}`;
+    const sessions = db.prepare(sessionSql).all();
+    for (const row of sessions) {
+        if (cutoffSeconds !== undefined && count(row.at) < cutoffSeconds) {
+            continue;
+        }
+        foldRow(row, totals, unpriced);
+    }
+}
+export async function createHermesReader() {
+    return {
+        descriptor: {
+            id: CLI_ID,
+            displayName: "Hermes Agent",
+            verified: true,
+            // One row per (session, model, task): the store already holds each call
+            // exactly once, so the only thing to avoid is reading a session's
+            // aggregate on top of its rows.
+            dedupStrategy: "last-write-wins",
+            costConfidence: "modeled",
+            requiresSqlite: true,
+        },
+        detect: async () => (await findStateDatabases()).length > 0,
+        scan: async (options) => {
+            const totals = emptyTotals();
+            const errors = [];
+            const unpriced = new Set();
+            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: hermesHome(),
+                    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: hermesHome(),
+                    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);
+            const cutoffSeconds = cutoffMs === undefined ? undefined : cutoffMs / 1000;
+            let filesScanned = 0;
+            for (const dbPath of await findStateDatabases()) {
+                let db;
+                try {
+                    // Read-only: Hermes may be writing to this file right now.
+                    db = new DatabaseSync(dbPath, { readOnly: true });
+                    filesScanned += 1;
+                    readStore(db, dbPath, cutoffSeconds, totals, unpriced, errors);
+                }
+                catch (error) {
+                    errors.push({
+                        cliId: CLI_ID,
+                        filePath: dbPath,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                finally {
+                    try {
+                        db?.close();
+                    }
+                    catch {
+                        // Already closed, or never opened.
+                    }
+                }
+            }
+            totals.unpricedModels = [...unpriced].sort();
+            return { cliId: CLI_ID, totals, filesScanned, errors };
+        },
+    };
+}

package/dist/localUsage/localUsageReaderRegistry.js

@@ -108,3 +108,46 @@ registerLocalUsageReader({
         return createCopilotCliReader();
     },
 });
+registerLocalUsageReader({
+    descriptor: {
+        id: "cursor",
+        displayName: "Cursor",
+        verified: true,
+        dedupStrategy: "last-write-wins",
+        costConfidence: "unavailable",
+        requiresSqlite: true,
+        requestUnit: "session-snapshot",
+    },
+    factory: async () => {
+        const { createCursorReader } = await import("./cursorReader.js");
+        return createCursorReader();
+    },
+});
+registerLocalUsageReader({
+    descriptor: {
+        id: "grok",
+        displayName: "Grok Build",
+        verified: true,
+        dedupStrategy: "last-write-wins",
+        costConfidence: "unavailable",
+        requiresSqlite: false,
+    },
+    factory: async () => {
+        const { createGrokReader } = await import("./grokReader.js");
+        return createGrokReader();
+    },
+});
+registerLocalUsageReader({
+    descriptor: {
+        id: "hermes",
+        displayName: "Hermes Agent",
+        verified: true,
+        dedupStrategy: "last-write-wins",
+        costConfidence: "modeled",
+        requiresSqlite: true,
+    },
+    factory: async () => {
+        const { createHermesReader } = await import("./hermesReader.js");
+        return createHermesReader();
+    },
+});

package/dist/types/localUsage.d.ts

@@ -22,7 +22,7 @@ export type LocalUsageCliId = "claude-code" | "codex" | "gemini-cli" | "opencode
  * that names it. `usage local --cli copilot-cli` still resolves, normalised
  * to "copilot" at the input boundary.
  */
- | "copilot-cli" | "cursor" | "amp" | "hermes" | "kiro" | "antigravity" | "grok";
+ | "copilot-cli" | "cursor" | "grok" | "hermes" | "amp" | "kiro" | "antigravity";
 /**
  * How much to trust a computed cost figure.
  *
@@ -39,6 +39,21 @@ export type LocalUsageCostConfidence = "modeled" | "unavailable" | "heuristic";
  * next reader — the aggregator does not branch on it.
  */
 export type LocalUsageDedupStrategy = "message-id-keep-max" | "last-write-wins" | "rowid-high-water-mark" | "session-dag";
+/**
+ * What one unit of `LocalUsageTotals.requests` actually counts.
+ *
+ * Not cosmetic. Every reader but one counts assistant turns, so the CLI could
+ * safely print "turns" for all of them. Cursor persists no per-turn record at
+ * all — only a snapshot of the current context, one per session however many
+ * turns that session ran — so printing "turns 1" for a two-hundred-turn
+ * session states something false. The unit travels with the number for the
+ * same reason `costConfidence` does: a figure rendered without saying what it
+ * counts is the failure this whole subsystem exists to avoid.
+ *
+ * Optional on the descriptor, defaulting to "turn", so adding it does not
+ * break an existing caller constructing a descriptor of its own.
+ */
+export type LocalUsageRequestUnit = "turn" | "session-snapshot";
 /** Aggregated totals for one CLI, one scan. */
 export type LocalUsageTotals = {
     requests: number;
@@ -86,6 +101,11 @@ export type LocalUsageReaderDescriptor = {
     costConfidence: LocalUsageCostConfidence;
     /** Whether reading this CLI's store needs a SQLite binding. */
     requiresSqlite: boolean;
+    /**
+     * What `LocalUsageTotals.requests` counts for this reader. Absent means
+     * "turn", which is what every reader except Cursor records.
+     */
+    requestUnit?: LocalUsageRequestUnit;
 };
 /** Options accepted by every reader's `scan()` and by the aggregator. */
 export type LocalUsageScanOptions = {
@@ -222,6 +242,61 @@ export type LocalUsageCopilotUsageRow = {
     reasoning_tokens: number | null;
     created_at: string | null;
 };
+/**
+ * One usage row as this subsystem reads it out of Hermes Agent's `state.db` —
+ * either a `session_model_usage` row, or a `sessions` row projected onto the
+ * same columns for a session that predates that table. Every column but the
+ * first five may be absent from an older schema and is selected with a
+ * default, so they are optional here. `at` is the row's last activity in
+ * epoch SECONDS, coalesced from whichever timestamp the schema has.
+ */
+export type LocalUsageHermesUsageRow = {
+    session_id: string;
+    model: string | null;
+    api_call_count: number | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    cache_read_tokens?: number | null;
+    cache_write_tokens?: number | null;
+    reasoning_tokens?: number | null;
+    estimated_cost_usd?: number | null;
+    actual_cost_usd?: number | null;
+    cost_status?: string | null;
+    at?: number | null;
+};
+/**
+ * The `usage` object on a Grok Build `turn_completed` session update, as
+ * appended to a session's `updates.jsonl`. camelCase, from the CLI's own
+ * serde definitions and confirmed on a real run. `modelUsage` holds the same
+ * shape per model id; `numTurns` is the process ledger's turn counter, which
+ * is how a reader tells a cumulative run from a fresh one — see
+ * `grokReader.ts`.
+ */
+export type LocalUsageGrokTurnUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedReadTokens?: number;
+    cacheCreationTokens?: number;
+    reasoningTokens?: number;
+    modelCalls?: number;
+    numTurns?: number;
+    modelUsage?: Record<string, unknown>;
+};
+/**
+ * One Grok Build completed turn after validation: every count a finite,
+ * non-negative safe integer, and the `modelUsage` keys collected. `turns` is
+ * the ledger's `numTurns`, which decides whether the next record continues
+ * this process run or starts a fresh one — see `grokReader.ts`.
+ */
+export type LocalUsageGrokTurn = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreation: number;
+    calls: number;
+    turns: number;
+    models: string[];
+};
 /**
  * The slice of `node:sqlite`'s `DatabaseSync` the OpenCode reader uses.
  *
@@ -230,6 +305,28 @@ export type LocalUsageCopilotUsageRow = {
  * runtime rather than trusting a type assertion — naming only what is actually
  * called keeps that check small and honest.
  */
+/**
+ * One decoded protobuf field from a Cursor root blob. Wire types 0 (varint)
+ * and 2 (length-delimited) only — the two Cursor actually uses; fixed-width
+ * fields are skipped by the decoder rather than represented.
+ */
+export type LocalUsageWireField = {
+    field: number;
+    kind: "varint";
+    value: number;
+} | {
+    field: number;
+    kind: "bytes";
+    value: Uint8Array;
+};
+/**
+ * One entry in Cursor's context breakdown — `system_prompt`, `tools`, `rules`
+ * and friends — carrying the token count that entry occupies in context.
+ */
+export type LocalUsageContextPart = {
+    name: string;
+    tokens: number;
+};
 export type LocalUsageSqliteDatabase = {
     prepare: (sql: string) => {
         all: (...params: unknown[]) => unknown[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.7.9",
+  "version": "12.9.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {