@juspay/neurolink 11.21.4 → 11.22.0

package/dist/cli/commands/usage.d.ts

@@ -0,0 +1,17 @@
+import type { CommandModule } from "yargs";
+import type { LocalUsageCommandArgs } from "../../types/index.js";
+/**
+ * `neurolink usage local` — token spend read from each CLI's own session logs.
+ *
+ * The proxy's ledger only sees traffic that went through it, which is a
+ * fraction of what a developer actually spends: it depends on each vendor
+ * shipping a base-URL override, and most do not. Every CLI writes a local
+ * transcript regardless, so this reads those instead — no auth, no vendor
+ * cooperation, no proxy in the request path, and it recovers history from
+ * before the proxy was ever installed.
+ */
+export declare class UsageCommandFactory {
+    static createUsageCommands(): CommandModule<object, LocalUsageCommandArgs>;
+    private static formatTokens;
+    private static executeLocal;
+}

package/dist/cli/commands/usage.js

@@ -0,0 +1,146 @@
+import chalk from "chalk";
+import { logger } from "../../utils/logger.js";
+/**
+ * `neurolink usage local` — token spend read from each CLI's own session logs.
+ *
+ * The proxy's ledger only sees traffic that went through it, which is a
+ * fraction of what a developer actually spends: it depends on each vendor
+ * shipping a base-URL override, and most do not. Every CLI writes a local
+ * transcript regardless, so this reads those instead — no auth, no vendor
+ * cooperation, no proxy in the request path, and it recovers history from
+ * before the proxy was ever installed.
+ */
+export class UsageCommandFactory {
+    static createUsageCommands() {
+        return {
+            command: "usage <subcommand>",
+            describe: "Token usage read from local CLI session logs",
+            builder: (yargs) => yargs.command({
+                command: "local",
+                describe: "Summarise token spend from each installed CLI's own session logs",
+                builder: (sub) => sub
+                    .option("since", {
+                    type: "number",
+                    default: 30,
+                    description: "Only read sessions modified within this many days (0 = all history)",
+                })
+                    .option("cli", {
+                    type: "string",
+                    description: "Limit to one CLI id (e.g. claude-code, codex, opencode)",
+                })
+                    .option("json", {
+                    type: "boolean",
+                    default: false,
+                    description: "Emit the raw report as JSON",
+                }),
+                handler: async (argv) => {
+                    // Single assertion, not a double. yargs types the sub-builder's
+                    // argv structurally; the fields below are the ones the builder
+                    // declares, so this stays overlap-checked by the compiler.
+                    await UsageCommandFactory.executeLocal({
+                        since: Number(argv.since ?? 30),
+                        json: Boolean(argv.json),
+                        ...(typeof argv.cli === "string" ? { cli: argv.cli } : {}),
+                    });
+                },
+            }),
+            handler: () => {
+                // yargs prints subcommand help when none is given.
+            },
+        };
+    }
+    static formatTokens(value) {
+        // Plain grouped digits rather than 1.2M: these are billing-adjacent
+        // figures and a reader comparing two rows needs the magnitudes to line up,
+        // not to be rounded into looking similar.
+        return value.toLocaleString("en-US");
+    }
+    static async executeLocal(argv) {
+        const { readAllLocalUsage, getLocalUsageDescriptors } = await import("../../localUsage/index.js");
+        // `--since 0` means all history — Infinity is the reader's sentinel for
+        // "no time filter", but 0 is what a person types. A NEGATIVE value is a
+        // mistake and must be rejected rather than folded in with 0: the previous
+        // expression sent -1 down the all-history path, so a typo produced the
+        // most expensive possible scan while the option's own help text says 0 is
+        // the way to ask for that.
+        if (!Number.isFinite(argv.since) || argv.since < 0) {
+            console.error(chalk.red(`--since must be zero or greater (0 means all history). Received: ${String(argv.since)}`));
+            process.exitCode = 1;
+            return;
+        }
+        const sinceDays = argv.since > 0 ? argv.since : Infinity;
+        // Validate BEFORE scanning. A typo should cost nothing, not a full sweep
+        // of every store followed by an empty result.
+        // `undefined` means the flag was not given. An empty string means it was
+        // given with no value, which is a mistake and must be rejected — a
+        // truthiness check treats the two as the same and silently scans every
+        // reader instead, reporting everything for a request that named nothing.
+        const wanted = argv.cli;
+        const known = getLocalUsageDescriptors().map((d) => d.id);
+        if (wanted !== undefined &&
+            !known.includes(wanted)) {
+            console.error(chalk.red(`Unknown CLI "${wanted}". Known readers: ${known.join(", ")}`));
+            process.exitCode = 1;
+            return;
+        }
+        const report = await readAllLocalUsage({
+            sinceDays,
+            // Passed down so only the requested reader opens its store at all.
+            ...(wanted !== undefined
+                ? { only: [wanted] }
+                : {}),
+        });
+        const rows = Object.entries(report.totals);
+        if (argv.json) {
+            logger.always(JSON.stringify(wanted ? { ...report, totals: Object.fromEntries(rows) } : report, null, 2));
+            return;
+        }
+        const window = sinceDays === Infinity ? "all history" : `last ${argv.since} days`;
+        logger.always(chalk.bold(`\nLocal CLI token usage — ${window}\n`));
+        // A reader that ran and found nothing in the window is a different fact
+        // from one that is not installed, and from one that failed. Printing a
+        // 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);
+        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)}`);
+            logger.always(`    input   ${UsageCommandFactory.formatTokens(totals.inputTokens)}` +
+                `    output ${UsageCommandFactory.formatTokens(totals.outputTokens)}` +
+                `    cached ${UsageCommandFactory.formatTokens(cached)}`);
+            // Cost and its confidence are printed together, always. A dollar figure
+            // shown without saying how it was arrived at is the thing this whole
+            // subsystem is trying not to do: "unavailable" means the CLI is a
+            // subscription and a per-token price would be invented, not that the
+            // lookup failed.
+            if (totals.costConfidence === "modeled") {
+                logger.always(`    cost    ${chalk.green(`$${totals.costUsd.toFixed(2)}`)} (modeled)` +
+                    (totals.unpricedRequests > 0
+                        ? chalk.dim(`  — ${totals.unpricedRequests} turns unpriced: ${totals.unpricedModels.join(", ")}`)
+                        : ""));
+            }
+            else {
+                logger.always(`    cost    ${chalk.dim("unavailable")} ` +
+                    chalk.dim(totals.costConfidence === "heuristic"
+                        ? "(estimated, not measured)"
+                        : "(subscription — a per-token price would be invented)"));
+            }
+            logger.always("");
+        }
+        if (quiet.length > 0) {
+            logger.always(chalk.dim(`  no usage in this window: ${quiet.map(([id]) => id).join(", ")}`));
+        }
+        if (report.notInstalled.length > 0) {
+            logger.always(chalk.dim(`  not installed: ${report.notInstalled.join(", ")}`));
+        }
+        for (const failure of report.failures) {
+            logger.always(chalk.yellow(`  ${failure.cliId} failed: ${failure.message}`));
+        }
+        logger.always("");
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/cli/parser.js

@@ -29,6 +29,7 @@ import { TaskCommandFactory } from "./commands/task.js";
 import { AutoresearchCommandFactory } from "./commands/autoresearch.js";
 import { voiceServerCommand } from "./commands/voiceServer.js";
 import { DocsCommandFactory } from "./commands/docs.js";
+import { UsageCommandFactory } from "./commands/usage.js";
 // Enhanced CLI with Professional UX
 export function initializeCliParser() {
     return (yargs(hideBin(process.argv))
@@ -156,6 +157,7 @@ export function initializeCliParser() {
         .command(CLICommandFactory.createGenerateCommand())
         // Docs MCP Server Command
         .command(DocsCommandFactory.createDocsCommand())
+        .command(UsageCommandFactory.createUsageCommands())
         // Stream Text Command - Using CLICommandFactory
         .command(CLICommandFactory.createStreamCommand())
         // Batch Processing Command - Using CLICommandFactory

package/dist/localUsage/index.d.ts

@@ -6,7 +6,7 @@
  * a local transcript regardless, so reading those covers the rest — and covers
  * history from before the proxy existed.
  */
-import type { LocalUsageAggregateReport, LocalUsageScanOptions } from "../types/index.js";
+import type { LocalUsageAggregateOptions, LocalUsageAggregateReport } from "../types/index.js";
 export { createLocalUsageReader, getLocalUsageDescriptors, getRegisteredLocalUsageCliIds, registerLocalUsageReader, } from "./localUsageReaderRegistry.js";
 /**
  * Scan every registered reader whose CLI is actually present on this machine.
@@ -15,4 +15,4 @@ export { createLocalUsageReader, getLocalUsageDescriptors, getRegisteredLocalUsa
  * the user never installed is not an error, and collapsing the two would make
  * a broken reader indistinguishable from an absent one.
  */
-export declare function readAllLocalUsage(options?: LocalUsageScanOptions): Promise<LocalUsageAggregateReport>;
+export declare function readAllLocalUsage(options?: LocalUsageAggregateOptions): Promise<LocalUsageAggregateReport>;

package/dist/localUsage/index.js

@@ -19,7 +19,14 @@ export async function readAllLocalUsage(options) {
     const totals = {};
     const failures = [];
     const notInstalled = [];
-    for (const cliId of getRegisteredLocalUsageCliIds()) {
+    // Filtered BEFORE construction, not after: `only` decides which stores are
+    // opened at all. Reading all of them and discarding the rest cost 28s for a
+    // single-CLI query that needs 10.
+    const requested = options?.only;
+    const cliIds = requested
+        ? getRegisteredLocalUsageCliIds().filter((id) => requested.includes(id))
+        : getRegisteredLocalUsageCliIds();
+    for (const cliId of cliIds) {
         try {
             const reader = await createLocalUsageReader(cliId);
             if (!(await reader.detect())) {

package/dist/types/localUsage.d.ts

@@ -169,3 +169,20 @@ export type LocalUsageSqliteDatabase = {
 export type LocalUsageSqliteDatabaseCtor = new (path: string, options?: {
     readOnly?: boolean;
 }) => LocalUsageSqliteDatabase;
+/** Arguments for the `neurolink usage local` command. */
+export type LocalUsageCommandArgs = {
+    since: number;
+    json: boolean;
+    cli?: string;
+};
+/**
+ * Options for scanning every registered reader at once.
+ *
+ * `only` is not a convenience filter applied to the results — it decides which
+ * readers are constructed and run at all. Scanning everything and discarding
+ * the rest turned a 10s single-CLI query into 28s of reading two other stores
+ * nobody asked for, one of them 742 MB.
+ */
+export type LocalUsageAggregateOptions = LocalUsageScanOptions & {
+    only?: LocalUsageCliId[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.21.4",
+  "version": "11.22.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": {