@inferhub/usage 0.1.0 → 0.1.2

package/bin/statusline.mjs

@@ -22,11 +22,16 @@ try {
 }
 
 try {
-  const { usage } = await client.fetchAccountUsageAuto({ window: "day" });
-  const sessionCost =
-    typeof session?.cost?.total_cost_usd === "number"
-      ? session.cost.total_cost_usd
-      : null;
+  // Prefer Claude's real session_id so /v1/me/usage can aggregate this conversation.
+  const sessionId =
+    (typeof session?.session_id === "string" && session.session_id) ||
+    (typeof session?.sessionId === "string" && session.sessionId) ||
+    undefined;
+
+  const { usage } = await client.fetchAccountUsageAuto({
+    window: "day",
+    sessionId,
+  });
   const contextPct =
     typeof session?.context_window?.used_percentage === "number"
       ? session.context_window.used_percentage
@@ -34,13 +39,12 @@ try {
   const model = session?.model?.display_name || session?.model?.id || null;
   process.stdout.write(
     client.formatStatusLine(usage, {
-      sessionCostUsd: sessionCost,
       contextPct,
       model,
     }) + "\n",
   );
 } catch (e) {
   const msg = e instanceof Error ? e.message : String(e);
-  process.stdout.write("IH · offline (" + msg.slice(0, 48) + ")\n");
+  process.stdout.write("InferHub · offline (" + msg.slice(0, 48) + ")\n");
   process.exitCode = 0;
 }

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { AccountUsage, FetchUsageOptions, ResolvedAuth, UsageWindowKind } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://api.inferhub.dev/v1";
 export declare function normalizeBaseUrl(input?: string | null): string;
-export declare function usageUrl(baseUrl: string, window?: UsageWindowKind, tz?: string): string;
+export declare function usageUrl(baseUrl: string, window?: UsageWindowKind, tz?: string, sessionId?: string): string;
 /** Resolve API key + base URL from env / agent config files. */
 export declare function resolveAuth(overrides?: Partial<ResolvedAuth>): ResolvedAuth | null;
 export declare function fetchAccountUsage(opts: FetchUsageOptions): Promise<AccountUsage>;

package/dist/client.js

@@ -12,9 +12,11 @@ export function normalizeBaseUrl(input) {
     }
     return u;
 }
-export function usageUrl(baseUrl, window = "day", tz = "UTC") {
+export function usageUrl(baseUrl, window = "day", tz = "UTC", sessionId) {
     const base = normalizeBaseUrl(baseUrl);
     const q = new URLSearchParams({ window, tz });
+    if (sessionId)
+        q.set("session_id", sessionId);
     return `${base}/me/usage?${q.toString()}`;
 }
 /** Resolve API key + base URL from env / agent config files. */
@@ -86,9 +88,9 @@ function tryReadJson(path) {
         return null;
     }
 }
-function cacheKey(apiKey, window, tz, baseUrl) {
+function cacheKey(apiKey, window, tz, baseUrl, sessionId = "") {
     const h = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
-    return `${h}|${normalizeBaseUrl(baseUrl)}|${window}|${tz}`;
+    return `${h}|${normalizeBaseUrl(baseUrl)}|${window}|${tz}|${sessionId}`;
 }
 function diskCachePath(key) {
     const dir = process.env.CLAUDE_PLUGIN_DATA ||
@@ -106,9 +108,10 @@ function diskCachePath(key) {
 export async function fetchAccountUsage(opts) {
     const window = opts.window ?? "day";
     const tz = opts.tz ?? "UTC";
+    const sessionId = opts.sessionId ?? "";
     const baseUrl = normalizeBaseUrl(opts.baseUrl);
     const ttlMs = (opts.cacheTtlSeconds ?? 30) * 1000;
-    const key = cacheKey(opts.apiKey, window, tz, baseUrl);
+    const key = cacheKey(opts.apiKey, window, tz, baseUrl, sessionId);
     const now = Date.now();
     if (!opts.force) {
         const hit = mem.get(key);
@@ -128,7 +131,7 @@ export async function fetchAccountUsage(opts) {
             /* ignore disk cache */
         }
     }
-    const url = usageUrl(baseUrl, window, tz);
+    const url = usageUrl(baseUrl, window, tz, sessionId || undefined);
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
         throw new Error("fetch is not available in this runtime");
@@ -139,6 +142,7 @@ export async function fetchAccountUsage(opts) {
             Authorization: `Bearer ${opts.apiKey}`,
             "x-api-key": opts.apiKey,
             Accept: "application/json",
+            ...(sessionId ? { "X-Session-Id": sessionId } : {}),
         },
         signal: opts.signal,
     });

package/dist/format.d.ts

@@ -2,11 +2,18 @@ import type { AccountUsage } from "./types.js";
 export declare function money(usdc: string | number | null | undefined, digits?: number): string;
 export declare function tokens(n: number | null | undefined): string;
 export declare function shortModel(model: string | null | undefined): string;
-/** Compact one-liner for Claude statusline / Codex Stop summary. */
+/**
+ * Compact one-liner for Claude statusline / Codex Stop summary.
+ *
+ * Shows InferHub-billed figures only. Claude's local `cost.total_cost_usd` is
+ * official list-price estimate and is NOT shown unless showEstimate=true.
+ */
 export declare function formatStatusLine(usage: AccountUsage, extras?: {
     sessionCostUsd?: number | null;
     contextPct?: number | null;
     model?: string | null;
+    /** When true, include Claude's local cost estimate as `est $…`. Default false. */
+    showEstimate?: boolean;
 }): string;
 /** Multi-line human report for /usage skills. */
 export declare function formatReport(usage: AccountUsage): string;

package/dist/format.js

@@ -20,12 +20,23 @@ export function shortModel(model) {
     const parts = model.split("/");
     return parts[parts.length - 1] || model;
 }
-/** Compact one-liner for Claude statusline / Codex Stop summary. */
+function spendOrActivity(spendUsdc, requests, totalTokens) {
+    const spend = Number(spendUsdc ?? 0);
+    if (spend > 0)
+        return money(spend);
+    return `${requests}r/${tokens(totalTokens)}`;
+}
+/**
+ * Compact one-liner for Claude statusline / Codex Stop summary.
+ *
+ * Shows InferHub-billed figures only. Claude's local `cost.total_cost_usd` is
+ * official list-price estimate and is NOT shown unless showEstimate=true.
+ */
 export function formatStatusLine(usage, extras) {
-    const sess = extras?.sessionCostUsd != null && Number.isFinite(extras.sessionCostUsd)
-        ? money(extras.sessionCostUsd)
+    const sess = usage.session
+        ? spendOrActivity(usage.session.spend_usdc, usage.session.requests, usage.session.total_tokens)
         : null;
-    const day = money(usage.window.spend_usdc);
+    const day = spendOrActivity(usage.window.spend_usdc, usage.window.requests, usage.window.total_tokens);
     const all = money(usage.all_time.spend_usdc);
     const bal = money(usage.balance.amount_usdc);
     const top = shortModel(usage.top_model?.model);
@@ -33,7 +44,7 @@ export function formatStatusLine(usage, extras) {
     const ctx = extras?.contextPct != null && Number.isFinite(extras.contextPct)
         ? `${Math.round(extras.contextPct)}%ctx`
         : null;
-    const parts = ["IH"];
+    const parts = ["InferHub"];
     if (model)
         parts.push(model);
     if (sess)
@@ -41,9 +52,16 @@ export function formatStatusLine(usage, extras) {
     parts.push(`${usage.window.kind} ${day}`);
     parts.push(`all ${all}`);
     parts.push(`bal ${bal}`);
-    parts.push(`top ${top}`);
+    if (top && top !== "—")
+        parts.push(`top ${top}`);
     if (ctx)
         parts.push(ctx);
+    if (extras?.showEstimate &&
+        extras.sessionCostUsd != null &&
+        Number.isFinite(extras.sessionCostUsd) &&
+        extras.sessionCostUsd > 0) {
+        parts.push(`est ${money(extras.sessionCostUsd)}`);
+    }
     return parts.join(" · ");
 }
 /** Multi-line human report for /usage skills. */
@@ -51,10 +69,11 @@ export function formatReport(usage) {
     const lines = [
         "InferHub usage",
         `  Balance:   ${money(usage.balance.amount_usdc)} USDC`,
-        `  ${usage.window.kind} window (${usage.window.tz}): ${money(usage.window.spend_usdc)} · ${usage.window.requests} req · ${tokens(usage.window.total_tokens)} tok`,
-        `  All-time:  ${money(usage.all_time.spend_usdc)} · ${usage.all_time.requests} req · ${tokens(usage.all_time.total_tokens)} tok`,
-        `  Top model: ${usage.top_model?.model ?? "—"} (${money(usage.top_model?.spend_usdc ?? 0)}, ${usage.top_model?.requests ?? 0} req)`,
     ];
+    if (usage.session) {
+        lines.push(`  Session:   ${money(usage.session.spend_usdc)} · ${usage.session.requests} req · ${tokens(usage.session.total_tokens)} tok (${usage.session.id.slice(0, 12)}…)`);
+    }
+    lines.push(`  ${usage.window.kind} window (${usage.window.tz}): ${money(usage.window.spend_usdc)} · ${usage.window.requests} req · ${tokens(usage.window.total_tokens)} tok`, `  All-time:  ${money(usage.all_time.spend_usdc)} · ${usage.all_time.requests} req · ${tokens(usage.all_time.total_tokens)} tok`, `  Top model: ${usage.top_model?.model ?? "—"} (${money(usage.top_model?.spend_usdc ?? 0)}, ${usage.top_model?.requests ?? 0} req)`);
     if (usage.cache?.cached)
         lines.push(`  (cached, ttl ${usage.cache.ttl_seconds}s)`);
     return lines.join("\n");

package/dist/format.test.js

@@ -7,8 +7,9 @@ test("normalizeBaseUrl adds /v1", () => {
 });
 test("usageUrl", () => {
     assert.equal(usageUrl("https://api.inferhub.dev", "day", "UTC"), "https://api.inferhub.dev/v1/me/usage?window=day&tz=UTC");
+    assert.equal(usageUrl("https://api.inferhub.dev", "day", "UTC", "abc"), "https://api.inferhub.dev/v1/me/usage?window=day&tz=UTC&session_id=abc");
 });
-test("formatStatusLine", () => {
+test("formatStatusLine is plain language", () => {
     const usage = {
         object: "account.usage",
         currency: "USDC",
@@ -18,34 +19,67 @@ test("formatStatusLine", () => {
             tz: "UTC",
             since: "",
             until: "",
-            requests: 3,
-            prompt_tokens: 100,
-            completion_tokens: 50,
-            total_tokens: 150,
-            spend_usdc: "0.012000",
+            requests: 86,
+            prompt_tokens: 14_000_000,
+            completion_tokens: 100_000,
+            total_tokens: 14_100_000,
+            spend_usdc: "0",
         },
         all_time: {
-            requests: 10,
-            prompt_tokens: 1000,
-            completion_tokens: 500,
-            total_tokens: 1500,
-            spend_usdc: "0.500000",
+            requests: 3890,
+            prompt_tokens: 300_000_000,
+            completion_tokens: 1_000_000,
+            total_tokens: 301_000_000,
+            spend_usdc: "0.410000",
+        },
+        session: {
+            id: "sess-1",
+            requests: 12,
+            prompt_tokens: 200_000,
+            completion_tokens: 5_000,
+            total_tokens: 205_000,
+            spend_usdc: "0",
+            since: null,
+            until: null,
         },
         top_model: {
-            model: "free/grok/grok-4.5",
-            requests: 8,
-            tokens: 1200,
-            spend_usdc: "0.400000",
+            model: "cx/gpt-5.5",
+            requests: 212,
+            tokens: 239830,
+            spend_usdc: "0.137155",
         },
         cache: { cached: false, ttl_seconds: 30 },
     };
     const line = formatStatusLine(usage, {
-        sessionCostUsd: 0.03,
-        contextPct: 12,
         model: "free/grok/grok-4.5",
+        contextPct: 8,
+        sessionCostUsd: 2.69,
     });
-    assert.match(line, /IH/);
-    assert.match(line, /bal \$1\.25/);
-    assert.match(line, /top grok-4\.5/);
+    assert.match(line, /^InferHub/);
+    assert.match(line, /session 12 req \/ 205\.0k tok \/ \$0/);
+    assert.match(line, /today 86 req \/ 14\.1M tok \/ \$0/);
+    assert.match(line, /all-time 3,890 req \/ 301\.0M tok \/ \$0\.41/);
+    assert.match(line, /balance \$1\.25/);
+    assert.match(line, /top gpt-5\.5/);
+    assert.match(line, /8% context/);
+    assert.doesNotMatch(line, /\bIH\b/);
+    assert.doesNotMatch(line, /0r\/0/);
+    assert.doesNotMatch(line, /claude-est/); // estimate off by default
+    // empty/zero session should be omitted (not "sess 0r/0")
+    const noSess = {
+        ...usage,
+        session: {
+            id: "empty",
+            requests: 0,
+            prompt_tokens: 0,
+            completion_tokens: 0,
+            total_tokens: 0,
+            spend_usdc: "0",
+            since: null,
+            until: null,
+        },
+    };
+    const line2 = formatStatusLine(noSess, { model: "Grok" });
+    assert.doesNotMatch(line2, /session /);
     assert.equal(money("0.001"), "$0.0010");
 });

package/dist/types.d.ts

@@ -24,6 +24,16 @@ export type AccountUsage = {
         total_tokens: number;
         spend_usdc: string;
     };
+    session: {
+        id: string;
+        requests: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        spend_usdc: string;
+        since: string | null;
+        until: string | null;
+    } | null;
     top_model: {
         model: string;
         requests: number;
@@ -41,6 +51,8 @@ export type FetchUsageOptions = {
     baseUrl?: string;
     window?: UsageWindowKind;
     tz?: string;
+    /** Conversation session id (X-Session-Id / sessionid.Derive). */
+    sessionId?: string;
     /** Force network; ignore process cache */
     force?: boolean;
     /** Client-side process cache TTL seconds (default 30) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferhub/usage",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared InferHub account usage client for coding-agent plugins",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.ts

@@ -1,205 +1,213 @@
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
-import type { AccountUsage, FetchUsageOptions, ResolvedAuth, UsageWindowKind } from "./types.js";
-
-export const DEFAULT_BASE_URL = "https://api.inferhub.dev/v1";
-
-const mem = new Map<string, { expires: number; value: AccountUsage }>();
-
-export function normalizeBaseUrl(input?: string | null): string {
-  let u = (input || DEFAULT_BASE_URL).trim().replace(/\/+$/, "");
-  // Accept API root without /v1
-  if (!u.endsWith("/v1")) {
-    u = `${u}/v1`;
-  }
-  return u;
-}
-
-export function usageUrl(baseUrl: string, window: UsageWindowKind = "day", tz = "UTC"): string {
-  const base = normalizeBaseUrl(baseUrl);
-  const q = new URLSearchParams({ window, tz });
-  return `${base}/me/usage?${q.toString()}`;
-}
-
-/** Resolve API key + base URL from env / agent config files. */
-export function resolveAuth(overrides: Partial<ResolvedAuth> = {}): ResolvedAuth | null {
-  if (overrides.apiKey) {
-    return {
-      apiKey: overrides.apiKey,
-      baseUrl: normalizeBaseUrl(overrides.baseUrl),
-      source: "override",
-    };
-  }
-
-  const envKey =
-    process.env.INFERHUB_API_KEY ||
-    process.env.ANTHROPIC_AUTH_TOKEN ||
-    process.env.ANTHROPIC_API_KEY ||
-    process.env.OPENAI_API_KEY;
-  const envBase =
-    process.env.INFERHUB_BASE_URL ||
-    process.env.ANTHROPIC_BASE_URL ||
-    process.env.OPENAI_BASE_URL;
-
-  if (envKey) {
-    return {
-      apiKey: envKey,
-      baseUrl: normalizeBaseUrl(envBase || DEFAULT_BASE_URL),
-      source: "env",
-    };
-  }
-
-  // OpenCode provider config
-  const oc = tryReadJson(join(homedir(), ".config", "opencode", "opencode.json"));
-  const ocKey = oc?.provider?.inferhub?.options?.apiKey;
-  const ocBase = oc?.provider?.inferhub?.options?.baseURL;
-  if (typeof ocKey === "string" && ocKey) {
-    return {
-      apiKey: ocKey,
-      baseUrl: normalizeBaseUrl(typeof ocBase === "string" ? ocBase : DEFAULT_BASE_URL),
-      source: "opencode.json",
-    };
-  }
-
-  // Claude settings env
-  const claude = tryReadJson(join(homedir(), ".claude", "settings.json"));
-  const cKey =
-    claude?.env?.ANTHROPIC_AUTH_TOKEN ||
-    claude?.env?.ANTHROPIC_API_KEY ||
-    claude?.env?.INFERHUB_API_KEY;
-  const cBase = claude?.env?.ANTHROPIC_BASE_URL || claude?.env?.INFERHUB_BASE_URL;
-  if (typeof cKey === "string" && cKey) {
-    return {
-      apiKey: cKey,
-      baseUrl: normalizeBaseUrl(typeof cBase === "string" ? cBase : DEFAULT_BASE_URL),
-      source: "claude settings",
-    };
-  }
-
-  // Codex auth.json
-  const codexAuth = tryReadJson(join(homedir(), ".codex", "auth.json"));
-  const codexKey = codexAuth?.OPENAI_API_KEY;
-  if (typeof codexKey === "string" && codexKey) {
-    return {
-      apiKey: codexKey,
-      baseUrl: normalizeBaseUrl(DEFAULT_BASE_URL),
-      source: "codex auth.json",
-    };
-  }
-
-  return null;
-}
-
-function tryReadJson(path: string): any | null {
-  try {
-    if (!existsSync(path)) return null;
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function cacheKey(apiKey: string, window: string, tz: string, baseUrl: string): string {
-  const h = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
-  return `${h}|${normalizeBaseUrl(baseUrl)}|${window}|${tz}`;
-}
-
-function diskCachePath(key: string): string {
-  const dir =
-    process.env.CLAUDE_PLUGIN_DATA ||
-    process.env.INFERHUB_CACHE_DIR ||
-    join(tmpdir(), "inferhub-usage");
-  try {
-    mkdirSync(dir, { recursive: true });
-  } catch {
-    /* ignore */
-  }
-  const safe = createHash("sha256").update(key).digest("hex").slice(0, 24);
-  return join(dir, `usage-${safe}.json`);
-}
-
-export async function fetchAccountUsage(opts: FetchUsageOptions): Promise<AccountUsage> {
-  const window = opts.window ?? "day";
-  const tz = opts.tz ?? "UTC";
-  const baseUrl = normalizeBaseUrl(opts.baseUrl);
-  const ttlMs = (opts.cacheTtlSeconds ?? 30) * 1000;
-  const key = cacheKey(opts.apiKey, window, tz, baseUrl);
-  const now = Date.now();
-
-  if (!opts.force) {
-    const hit = mem.get(key);
-    if (hit && hit.expires > now) return hit.value;
-    try {
-      const p = diskCachePath(key);
-      if (existsSync(p)) {
-        const raw = JSON.parse(readFileSync(p, "utf8")) as {
-          expires: number;
-          value: AccountUsage;
-        };
-        if (raw.expires > now && raw.value?.object === "account.usage") {
-          mem.set(key, raw);
-          return raw.value;
-        }
-      }
-    } catch {
-      /* ignore disk cache */
-    }
-  }
-
-  const url = usageUrl(baseUrl, window, tz);
-  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-  if (!fetchImpl) {
-    throw new Error("fetch is not available in this runtime");
-  }
-
-  const res = await fetchImpl(url, {
-    method: "GET",
-    headers: {
-      Authorization: `Bearer ${opts.apiKey}`,
-      "x-api-key": opts.apiKey,
-      Accept: "application/json",
-    },
-    signal: opts.signal,
-  });
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new Error(`InferHub usage HTTP ${res.status}: ${body.slice(0, 300)}`);
-  }
-
-  const value = (await res.json()) as AccountUsage;
-  if (!value || value.object !== "account.usage") {
-    throw new Error("unexpected usage response shape");
-  }
-
-  const entry = { expires: now + ttlMs, value };
-  mem.set(key, entry);
-  try {
-    writeFileSync(diskCachePath(key), JSON.stringify(entry));
-  } catch {
-    /* ignore */
-  }
-  return value;
-}
-
-export async function fetchAccountUsageAuto(
-  opts: Omit<FetchUsageOptions, "apiKey" | "baseUrl"> & {
-    apiKey?: string;
-    baseUrl?: string;
-  } = {},
-): Promise<{ usage: AccountUsage; auth: ResolvedAuth }> {
-  const auth = resolveAuth({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
-  if (!auth) {
-    throw new Error(
-      "No InferHub API key found. Set INFERHUB_API_KEY or configure Claude/Codex/OpenCode via @inferhub/helper.",
-    );
-  }
-  const usage = await fetchAccountUsage({
-    ...opts,
-    apiKey: auth.apiKey,
-    baseUrl: auth.baseUrl,
-  });
-  return { usage, auth };
-}
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AccountUsage, FetchUsageOptions, ResolvedAuth, UsageWindowKind } from "./types.js";
+
+export const DEFAULT_BASE_URL = "https://api.inferhub.dev/v1";
+
+const mem = new Map<string, { expires: number; value: AccountUsage }>();
+
+export function normalizeBaseUrl(input?: string | null): string {
+  let u = (input || DEFAULT_BASE_URL).trim().replace(/\/+$/, "");
+  // Accept API root without /v1
+  if (!u.endsWith("/v1")) {
+    u = `${u}/v1`;
+  }
+  return u;
+}
+
+export function usageUrl(
+  baseUrl: string,
+  window: UsageWindowKind = "day",
+  tz = "UTC",
+  sessionId?: string,
+): string {
+  const base = normalizeBaseUrl(baseUrl);
+  const q = new URLSearchParams({ window, tz });
+  if (sessionId) q.set("session_id", sessionId);
+  return `${base}/me/usage?${q.toString()}`;
+}
+
+/** Resolve API key + base URL from env / agent config files. */
+export function resolveAuth(overrides: Partial<ResolvedAuth> = {}): ResolvedAuth | null {
+  if (overrides.apiKey) {
+    return {
+      apiKey: overrides.apiKey,
+      baseUrl: normalizeBaseUrl(overrides.baseUrl),
+      source: "override",
+    };
+  }
+
+  const envKey =
+    process.env.INFERHUB_API_KEY ||
+    process.env.ANTHROPIC_AUTH_TOKEN ||
+    process.env.ANTHROPIC_API_KEY ||
+    process.env.OPENAI_API_KEY;
+  const envBase =
+    process.env.INFERHUB_BASE_URL ||
+    process.env.ANTHROPIC_BASE_URL ||
+    process.env.OPENAI_BASE_URL;
+
+  if (envKey) {
+    return {
+      apiKey: envKey,
+      baseUrl: normalizeBaseUrl(envBase || DEFAULT_BASE_URL),
+      source: "env",
+    };
+  }
+
+  // OpenCode provider config
+  const oc = tryReadJson(join(homedir(), ".config", "opencode", "opencode.json"));
+  const ocKey = oc?.provider?.inferhub?.options?.apiKey;
+  const ocBase = oc?.provider?.inferhub?.options?.baseURL;
+  if (typeof ocKey === "string" && ocKey) {
+    return {
+      apiKey: ocKey,
+      baseUrl: normalizeBaseUrl(typeof ocBase === "string" ? ocBase : DEFAULT_BASE_URL),
+      source: "opencode.json",
+    };
+  }
+
+  // Claude settings env
+  const claude = tryReadJson(join(homedir(), ".claude", "settings.json"));
+  const cKey =
+    claude?.env?.ANTHROPIC_AUTH_TOKEN ||
+    claude?.env?.ANTHROPIC_API_KEY ||
+    claude?.env?.INFERHUB_API_KEY;
+  const cBase = claude?.env?.ANTHROPIC_BASE_URL || claude?.env?.INFERHUB_BASE_URL;
+  if (typeof cKey === "string" && cKey) {
+    return {
+      apiKey: cKey,
+      baseUrl: normalizeBaseUrl(typeof cBase === "string" ? cBase : DEFAULT_BASE_URL),
+      source: "claude settings",
+    };
+  }
+
+  // Codex auth.json
+  const codexAuth = tryReadJson(join(homedir(), ".codex", "auth.json"));
+  const codexKey = codexAuth?.OPENAI_API_KEY;
+  if (typeof codexKey === "string" && codexKey) {
+    return {
+      apiKey: codexKey,
+      baseUrl: normalizeBaseUrl(DEFAULT_BASE_URL),
+      source: "codex auth.json",
+    };
+  }
+
+  return null;
+}
+
+function tryReadJson(path: string): any | null {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function cacheKey(apiKey: string, window: string, tz: string, baseUrl: string, sessionId = ""): string {
+  const h = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+  return `${h}|${normalizeBaseUrl(baseUrl)}|${window}|${tz}|${sessionId}`;
+}
+
+function diskCachePath(key: string): string {
+  const dir =
+    process.env.CLAUDE_PLUGIN_DATA ||
+    process.env.INFERHUB_CACHE_DIR ||
+    join(tmpdir(), "inferhub-usage");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    /* ignore */
+  }
+  const safe = createHash("sha256").update(key).digest("hex").slice(0, 24);
+  return join(dir, `usage-${safe}.json`);
+}
+
+export async function fetchAccountUsage(opts: FetchUsageOptions): Promise<AccountUsage> {
+  const window = opts.window ?? "day";
+  const tz = opts.tz ?? "UTC";
+  const sessionId = opts.sessionId ?? "";
+  const baseUrl = normalizeBaseUrl(opts.baseUrl);
+  const ttlMs = (opts.cacheTtlSeconds ?? 30) * 1000;
+  const key = cacheKey(opts.apiKey, window, tz, baseUrl, sessionId);
+  const now = Date.now();
+
+  if (!opts.force) {
+    const hit = mem.get(key);
+    if (hit && hit.expires > now) return hit.value;
+    try {
+      const p = diskCachePath(key);
+      if (existsSync(p)) {
+        const raw = JSON.parse(readFileSync(p, "utf8")) as {
+          expires: number;
+          value: AccountUsage;
+        };
+        if (raw.expires > now && raw.value?.object === "account.usage") {
+          mem.set(key, raw);
+          return raw.value;
+        }
+      }
+    } catch {
+      /* ignore disk cache */
+    }
+  }
+
+  const url = usageUrl(baseUrl, window, tz, sessionId || undefined);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error("fetch is not available in this runtime");
+  }
+
+  const res = await fetchImpl(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${opts.apiKey}`,
+      "x-api-key": opts.apiKey,
+      Accept: "application/json",
+      ...(sessionId ? { "X-Session-Id": sessionId } : {}),
+    },
+    signal: opts.signal,
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`InferHub usage HTTP ${res.status}: ${body.slice(0, 300)}`);
+  }
+
+  const value = (await res.json()) as AccountUsage;
+  if (!value || value.object !== "account.usage") {
+    throw new Error("unexpected usage response shape");
+  }
+
+  const entry = { expires: now + ttlMs, value };
+  mem.set(key, entry);
+  try {
+    writeFileSync(diskCachePath(key), JSON.stringify(entry));
+  } catch {
+    /* ignore */
+  }
+  return value;
+}
+
+export async function fetchAccountUsageAuto(
+  opts: Omit<FetchUsageOptions, "apiKey" | "baseUrl"> & {
+    apiKey?: string;
+    baseUrl?: string;
+  } = {},
+): Promise<{ usage: AccountUsage; auth: ResolvedAuth }> {
+  const auth = resolveAuth({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+  if (!auth) {
+    throw new Error(
+      "No InferHub API key found. Set INFERHUB_API_KEY or configure Claude/Codex/OpenCode via @inferhub/helper.",
+    );
+  }
+  const usage = await fetchAccountUsage({
+    ...opts,
+    apiKey: auth.apiKey,
+    baseUrl: auth.baseUrl,
+  });
+  return { usage, auth };
+}

package/src/format.test.ts

@@ -13,9 +13,13 @@ test("usageUrl", () => {
     usageUrl("https://api.inferhub.dev", "day", "UTC"),
     "https://api.inferhub.dev/v1/me/usage?window=day&tz=UTC",
   );
+  assert.equal(
+    usageUrl("https://api.inferhub.dev", "day", "UTC", "abc"),
+    "https://api.inferhub.dev/v1/me/usage?window=day&tz=UTC&session_id=abc",
+  );
 });
 
-test("formatStatusLine", () => {
+test("formatStatusLine is plain language", () => {
   const usage: AccountUsage = {
     object: "account.usage",
     currency: "USDC",
@@ -25,34 +29,71 @@ test("formatStatusLine", () => {
       tz: "UTC",
       since: "",
       until: "",
-      requests: 3,
-      prompt_tokens: 100,
-      completion_tokens: 50,
-      total_tokens: 150,
-      spend_usdc: "0.012000",
+      requests: 86,
+      prompt_tokens: 14_000_000,
+      completion_tokens: 100_000,
+      total_tokens: 14_100_000,
+      spend_usdc: "0",
     },
     all_time: {
-      requests: 10,
-      prompt_tokens: 1000,
-      completion_tokens: 500,
-      total_tokens: 1500,
-      spend_usdc: "0.500000",
+      requests: 3890,
+      prompt_tokens: 300_000_000,
+      completion_tokens: 1_000_000,
+      total_tokens: 301_000_000,
+      spend_usdc: "0.410000",
+    },
+    session: {
+      id: "sess-1",
+      requests: 12,
+      prompt_tokens: 200_000,
+      completion_tokens: 5_000,
+      total_tokens: 205_000,
+      spend_usdc: "0",
+      since: null,
+      until: null,
     },
     top_model: {
-      model: "free/grok/grok-4.5",
-      requests: 8,
-      tokens: 1200,
-      spend_usdc: "0.400000",
+      model: "cx/gpt-5.5",
+      requests: 212,
+      tokens: 239830,
+      spend_usdc: "0.137155",
     },
     cache: { cached: false, ttl_seconds: 30 },
   };
+
   const line = formatStatusLine(usage, {
-    sessionCostUsd: 0.03,
-    contextPct: 12,
     model: "free/grok/grok-4.5",
+    contextPct: 8,
+    sessionCostUsd: 2.69,
   });
-  assert.match(line, /IH/);
-  assert.match(line, /bal \$1\.25/);
-  assert.match(line, /top grok-4\.5/);
+
+  assert.match(line, /^InferHub/);
+  assert.match(line, /session 12 req \/ 205\.0k tok \/ \$0/);
+  assert.match(line, /today 86 req \/ 14\.1M tok \/ \$0/);
+  assert.match(line, /all-time 3,890 req \/ 301\.0M tok \/ \$0\.41/);
+  assert.match(line, /balance \$1\.25/);
+  assert.match(line, /top gpt-5\.5/);
+  assert.match(line, /8% context/);
+  assert.doesNotMatch(line, /\bIH\b/);
+  assert.doesNotMatch(line, /0r\/0/);
+  assert.doesNotMatch(line, /claude-est/); // estimate off by default
+
+  // empty/zero session should be omitted (not "sess 0r/0")
+  const noSess: AccountUsage = {
+    ...usage,
+    session: {
+      id: "empty",
+      requests: 0,
+      prompt_tokens: 0,
+      completion_tokens: 0,
+      total_tokens: 0,
+      spend_usdc: "0",
+      since: null,
+      until: null,
+    },
+  };
+  const line2 = formatStatusLine(noSess, { model: "Grok" });
+  assert.doesNotMatch(line2, /session /);
+
   assert.equal(money("0.001"), "$0.0010");
 });

package/src/format.ts

@@ -20,20 +20,44 @@ export function shortModel(model: string | null | undefined): string {
   return parts[parts.length - 1] || model;
 }
 
-/** Compact one-liner for Claude statusline / Codex Stop summary. */
+function spendOrActivity(
+  spendUsdc: string | number | null | undefined,
+  requests: number,
+  totalTokens: number,
+): string {
+  const spend = Number(spendUsdc ?? 0);
+  if (spend > 0) return money(spend);
+  return `${requests}r/${tokens(totalTokens)}`;
+}
+
+/**
+ * Compact one-liner for Claude statusline / Codex Stop summary.
+ *
+ * Shows InferHub-billed figures only. Claude's local `cost.total_cost_usd` is
+ * official list-price estimate and is NOT shown unless showEstimate=true.
+ */
 export function formatStatusLine(
   usage: AccountUsage,
   extras?: {
     sessionCostUsd?: number | null;
     contextPct?: number | null;
     model?: string | null;
+    /** When true, include Claude's local cost estimate as `est $…`. Default false. */
+    showEstimate?: boolean;
   },
 ): string {
-  const sess =
-    extras?.sessionCostUsd != null && Number.isFinite(extras.sessionCostUsd)
-      ? money(extras.sessionCostUsd)
-      : null;
-  const day = money(usage.window.spend_usdc);
+  const sess = usage.session
+    ? spendOrActivity(
+        usage.session.spend_usdc,
+        usage.session.requests,
+        usage.session.total_tokens,
+      )
+    : null;
+  const day = spendOrActivity(
+    usage.window.spend_usdc,
+    usage.window.requests,
+    usage.window.total_tokens,
+  );
   const all = money(usage.all_time.spend_usdc);
   const bal = money(usage.balance.amount_usdc);
   const top = shortModel(usage.top_model?.model);
@@ -43,14 +67,24 @@ export function formatStatusLine(
       ? `${Math.round(extras.contextPct)}%ctx`
       : null;
 
-  const parts: string[] = ["IH"];
+  const parts: string[] = ["InferHub"];
   if (model) parts.push(model);
   if (sess) parts.push(`sess ${sess}`);
   parts.push(`${usage.window.kind} ${day}`);
   parts.push(`all ${all}`);
   parts.push(`bal ${bal}`);
-  parts.push(`top ${top}`);
+  if (top && top !== "—") parts.push(`top ${top}`);
   if (ctx) parts.push(ctx);
+
+  if (
+    extras?.showEstimate &&
+    extras.sessionCostUsd != null &&
+    Number.isFinite(extras.sessionCostUsd) &&
+    extras.sessionCostUsd > 0
+  ) {
+    parts.push(`est ${money(extras.sessionCostUsd)}`);
+  }
+
   return parts.join(" · ");
 }
 
@@ -59,10 +93,17 @@ export function formatReport(usage: AccountUsage): string {
   const lines = [
     "InferHub usage",
     `  Balance:   ${money(usage.balance.amount_usdc)} USDC`,
+  ];
+  if (usage.session) {
+    lines.push(
+      `  Session:   ${money(usage.session.spend_usdc)} · ${usage.session.requests} req · ${tokens(usage.session.total_tokens)} tok (${usage.session.id.slice(0, 12)}…)`,
+    );
+  }
+  lines.push(
     `  ${usage.window.kind} window (${usage.window.tz}): ${money(usage.window.spend_usdc)} · ${usage.window.requests} req · ${tokens(usage.window.total_tokens)} tok`,
     `  All-time:  ${money(usage.all_time.spend_usdc)} · ${usage.all_time.requests} req · ${tokens(usage.all_time.total_tokens)} tok`,
     `  Top model: ${usage.top_model?.model ?? "—"} (${money(usage.top_model?.spend_usdc ?? 0)}, ${usage.top_model?.requests ?? 0} req)`,
-  ];
+  );
   if (usage.cache?.cached) lines.push(`  (cached, ttl ${usage.cache.ttl_seconds}s)`);
   return lines.join("\n");
 }

package/src/types.ts

@@ -25,6 +25,16 @@ export type AccountUsage = {
     total_tokens: number;
     spend_usdc: string;
   };
+  session: {
+    id: string;
+    requests: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    spend_usdc: string;
+    since: string | null;
+    until: string | null;
+  } | null;
   top_model: {
     model: string;
     requests: number;
@@ -43,6 +53,8 @@ export type FetchUsageOptions = {
   baseUrl?: string;
   window?: UsageWindowKind;
   tz?: string;
+  /** Conversation session id (X-Session-Id / sessionid.Derive). */
+  sessionId?: string;
   /** Force network; ignore process cache */
   force?: boolean;
   /** Client-side process cache TTL seconds (default 30) */