vibeusage 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,8 @@
   },
   "dependencies": {
     "@insforge/sdk": "1.2.2",
-    "proper-lockfile": "^4.1.2"
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@sourcegraph/scip-typescript": "^0.3.6",

package/src/commands/doctor.js

@@ -179,9 +179,12 @@ function runAuditTokensAll({ opts, config }) {
       anyHardError = true;
     }
     if (result.ok && result.exceedsThreshold) anyExceeds = true;
-    // no-local-sessions is informational, not a hard error; other non-ok states
-    // (cannot-resolve-user-id, insforge-db-query-failed, etc.) count as errors.
-    if (!result.ok && result.error !== "no-local-sessions") anyHardError = true;
+    // no-local-sessions and audit-not-applicable are informational, not hard
+    // errors. The latter means the source has no independent ground-truth to
+    // compare against the DB (e.g. hermes plugin-ledger is the same data that
+    // already feeds the DB).
+    const informationalErrors = new Set(["no-local-sessions", "audit-not-applicable"]);
+    if (!result.ok && !informationalErrors.has(result.error)) anyHardError = true;
     perSource.push(result);
   }
 
@@ -207,8 +210,14 @@ function runAuditTokensAll({ opts, config }) {
           `${r.source.padEnd(12)}  ${statusText.padEnd(22)}  ${drift.padStart(10)}  ${String(r.filesScanned).padStart(6)}  ${String(r.usageLines).padStart(6)}\n`,
         );
       } else {
-        const statusText =
-          r.error === "no-local-sessions" ? "no local sessions" : `ERR ${r.error}`;
+        let statusText;
+        if (r.error === "no-local-sessions") {
+          statusText = "no local sessions";
+        } else if (r.error === "audit-not-applicable") {
+          statusText = "N/A";
+        } else {
+          statusText = `ERR ${r.error}`;
+        }
         process.stdout.write(
           `${r.source.padEnd(12)}  ${statusText.padEnd(22)}  ${"—".padStart(10)}  ${"—".padStart(6)}  ${"—".padStart(6)}\n`,
         );

package/src/commands/sync.js

@@ -534,11 +534,11 @@ async function parseHermesUsageLedger({ trackerDir, cursors, queuePath }) {
       typeof event.model === "string" && event.model.trim() ? event.model.trim() : "unknown";
     const source = "hermes";
     const delta = {
-      input_tokens: Math.max(0, Number(event.input_tokens || 0)),
-      cached_input_tokens: Math.max(
+      input_tokens: Math.max(
         0,
-        Number(event.cache_read_tokens || 0) + Number(event.cache_write_tokens || 0),
+        Number(event.input_tokens || 0) + Number(event.cache_write_tokens || 0),
       ),
+      cached_input_tokens: Math.max(0, Number(event.cache_read_tokens || 0)),
       output_tokens: Math.max(0, Number(event.output_tokens || 0)),
       reasoning_output_tokens: Math.max(0, Number(event.reasoning_tokens || 0)),
       total_tokens: Math.max(0, Number(event.total_tokens || 0)),
@@ -554,6 +554,19 @@ async function parseHermesUsageLedger({ trackerDir, cursors, queuePath }) {
       continue;
     }
 
+    // Fallback: if all fine-grained channels are 0 but total_tokens > 0,
+    // route total into output so the event isn't silently dropped.
+    // This handles upstream plugins that only report total_tokens.
+    if (
+      delta.input_tokens === 0 &&
+      delta.cached_input_tokens === 0 &&
+      delta.output_tokens === 0 &&
+      delta.reasoning_output_tokens === 0 &&
+      delta.total_tokens > 0
+    ) {
+      delta.output_tokens = delta.total_tokens;
+    }
+
     const bucket = getHourlyBucket(hourlyState, source, model, bucketStart);
     addTotals(bucket.totals, delta);
     touchedBuckets.add(bucketKey(source, model, bucketStart));

package/src/lib/hermes-config.js

@@ -4,6 +4,11 @@ const fs = require("node:fs/promises");
 const fssync = require("node:fs");
 
 const { ensureDir, writeFileAtomic } = require("./fs");
+const {
+  addEnabledPlugin,
+  removeEnabledPlugin,
+  probeEnabledPlugin,
+} = require("./hermes-plugins-config");
 
 const HERMES_PLUGIN_ID = "vibeusage";
 const HERMES_PLUGIN_MARKER = "VIBEUSAGE_HERMES_PLUGIN";
@@ -78,11 +83,33 @@ async function probeHermesPlugin({ home = os.homedir(), env = process.env, track
     };
   }
 
-  const configured = yamlState.value === expectedYaml && initState.value === expectedInit;
+  const filesMatch = yamlState.value === expectedYaml && initState.value === expectedInit;
+
+  // Hermes user plugins are opt-in: the hooks only fire if vibeusage is in
+  // plugins.enabled. Files-on-disk are necessary but NOT sufficient — without
+  // the allow-list entry the ledger stays empty and we silently report 0
+  // tokens forever (see hermes_cli/plugins.py:_get_enabled_plugins).
+  const enabledState = await probeEnabledPlugin({ home, env, name: HERMES_PLUGIN_ID });
+  const isEnabled = enabledState.state === "enabled";
+
+  if (!filesMatch || !isEnabled) {
+    return {
+      configured: false,
+      status: "drifted",
+      detail: "Run vibeusage init to reconcile plugin",
+      filesMatch,
+      enabled: isEnabled,
+      enabledState: enabledState.state,
+      ...paths,
+    };
+  }
+
   return {
-    configured,
-    status: configured ? "ready" : "drifted",
-    detail: configured ? "Plugin installed" : "Run vibeusage init to reconcile plugin",
+    configured: true,
+    status: "ready",
+    detail: "Plugin installed",
+    filesMatch: true,
+    enabled: true,
     ...paths,
   };
 }
@@ -93,30 +120,76 @@ async function installHermesPlugin({ home = os.homedir(), env = process.env, tra
   const nextInit = buildHermesPluginInit({ ledgerPath: paths.ledgerPath });
   const currentYaml = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
   const currentInit = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
-  const changed = currentYaml !== nextYaml || currentInit !== nextInit;
+  const filesChanged = currentYaml !== nextYaml || currentInit !== nextInit;
 
   await ensureDir(paths.pluginDir);
   await writeFileAtomic(paths.pluginYamlPath, nextYaml);
   await writeFileAtomic(paths.pluginInitPath, nextInit);
-  return { configured: true, changed, ...paths };
+
+  // Also opt the plugin into Hermes' allow-list. Hermes loads user plugins
+  // only when their name appears in plugins.enabled (post v20→v21 migration).
+  // Without this step the hooks never fire and the ledger stays empty.
+  let enabledChanged = false;
+  let enableSkippedReason = null;
+  try {
+    const enableResult = await addEnabledPlugin({ home, env, name: HERMES_PLUGIN_ID });
+    enabledChanged = Boolean(enableResult.changed);
+  } catch (err) {
+    // Refuse to clobber malformed user config; surface the reason but don't
+    // throw — the file install half still has value, and the user can rerun
+    // init after fixing config.yaml.
+    enableSkippedReason = err && err.code ? err.code : "enable-failed";
+  }
+
+  return {
+    configured: enableSkippedReason === null,
+    changed: filesChanged || enabledChanged,
+    filesChanged,
+    enabledChanged,
+    enableSkippedReason,
+    ...paths,
+  };
 }
 
 async function removeHermesPlugin({ home = os.homedir(), env = process.env, trackerDir } = {}) {
   const paths = resolveHermesPluginPaths({ home, env, trackerDir });
   const hadPluginDir = await pathExists(paths.pluginDir);
+
+  // Always try to clean up the allow-list entry, even if the plugin dir is
+  // already gone — config.yaml could otherwise be left referencing a plugin
+  // that no longer exists.
+  let enabledChanged = false;
+  try {
+    const enableResult = await removeEnabledPlugin({ home, env, name: HERMES_PLUGIN_ID });
+    enabledChanged = Boolean(enableResult.changed);
+  } catch (_err) {
+    // Best-effort; mirrors the behaviour above. Don't block file removal on
+    // a malformed config.yaml.
+  }
+
   if (!hadPluginDir) {
-    return { removed: false, skippedReason: "plugin-missing", ...paths };
+    return {
+      removed: enabledChanged,
+      skippedReason: enabledChanged ? null : "plugin-missing",
+      enabledChanged,
+      ...paths,
+    };
   }
 
   const yamlText = await fs.readFile(paths.pluginYamlPath, "utf8").catch(() => null);
   const initText = await fs.readFile(paths.pluginInitPath, "utf8").catch(() => null);
   const markerPresent = hasHermesPluginMarker(yamlText) && hasHermesPluginMarker(initText);
   if (!markerPresent) {
-    return { removed: false, skippedReason: "unexpected-content", ...paths };
+    return {
+      removed: false,
+      skippedReason: "unexpected-content",
+      enabledChanged,
+      ...paths,
+    };
   }
 
   await fs.rm(paths.pluginDir, { recursive: true, force: true }).catch(() => {});
-  return { removed: true, ...paths };
+  return { removed: true, enabledChanged, ...paths };
 }
 
 function buildHermesPluginYaml() {

package/src/lib/hermes-plugins-config.js

@@ -0,0 +1,266 @@
+"use strict";
+
+/**
+ * Manage the `plugins.enabled` allow-list inside Hermes' config.yaml.
+ *
+ * Hermes (>= the v20→v21 migration) loads user plugins on an opt-in basis:
+ * a plugin in `~/.hermes/plugins/<name>/` only fires its hooks if its name
+ * appears in `plugins.enabled` of `~/.hermes/config.yaml` (see
+ * `hermes_cli/plugins.py:_get_enabled_plugins` and the discovery loop at
+ * `hermes_cli/plugins.py:641`).
+ *
+ * `installHermesPlugin` therefore must do TWO things to actually wire up the
+ * vibeusage hook:
+ *   1. Drop the plugin files into `~/.hermes/plugins/vibeusage/` (handled by
+ *      `hermes-config.js`).
+ *   2. Make sure `vibeusage` is listed under `plugins.enabled` here.
+ *
+ * Implementation notes:
+ *   - We use the `yaml` package's `parseDocument` to preserve user comments,
+ *     anchors, and key order. Plain `yaml.parse` + `yaml.stringify` would lose
+ *     all of that.
+ *   - All operations are idempotent. An already-enabled plugin stays as-is and
+ *     the function reports `changed: false`.
+ *   - The file is written atomically via writeFileAtomic to avoid leaving the
+ *     user with a half-written config.yaml on crash.
+ */
+
+const os = require("node:os");
+const path = require("node:path");
+const fs = require("node:fs/promises");
+
+const YAML = require("yaml");
+const { writeFileAtomic } = require("./fs");
+
+const HERMES_CONFIG_FILENAME = "config.yaml";
+
+function resolveHermesConfigPath({ home = os.homedir(), env = process.env } = {}) {
+  const explicit = typeof env.HERMES_HOME === "string" ? env.HERMES_HOME.trim() : "";
+  const hermesHome = explicit ? path.resolve(explicit) : path.join(home, ".hermes");
+  return path.join(hermesHome, HERMES_CONFIG_FILENAME);
+}
+
+/**
+ * Probe whether a plugin name is currently enabled in `plugins.enabled`.
+ *
+ * Returns one of:
+ *   - { state: "enabled" } — name appears in plugins.enabled
+ *   - { state: "missing-key" } — config exists but plugins.enabled key is absent
+ *   - { state: "missing-name" } — plugins.enabled exists but does not contain the name
+ *   - { state: "config-missing" } — config.yaml does not exist
+ *   - { state: "config-unreadable", error } — read or parse error
+ */
+async function probeEnabledPlugin({ home, env, name } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("name is required");
+  }
+  const configPath = resolveHermesConfigPath({ home, env });
+
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return { state: "config-missing", configPath };
+    }
+    return {
+      state: "config-unreadable",
+      error: err && err.message ? err.message : String(err),
+      configPath,
+    };
+  }
+
+  let doc;
+  try {
+    doc = YAML.parseDocument(raw);
+  } catch (err) {
+    return {
+      state: "config-unreadable",
+      error: err && err.message ? err.message : String(err),
+      configPath,
+    };
+  }
+  if (doc.errors && doc.errors.length > 0) {
+    return {
+      state: "config-unreadable",
+      error: doc.errors[0].message || "config.yaml has YAML errors",
+      configPath,
+    };
+  }
+
+  const enabled = doc.getIn(["plugins", "enabled"], true);
+  if (enabled === undefined) {
+    return { state: "missing-key", configPath };
+  }
+  const list = enabled && typeof enabled.toJSON === "function" ? enabled.toJSON() : enabled;
+  if (!Array.isArray(list)) {
+    return { state: "missing-key", configPath };
+  }
+  if (list.includes(name)) {
+    return { state: "enabled", configPath };
+  }
+  return { state: "missing-name", configPath };
+}
+
+/**
+ * Idempotently add `name` to plugins.enabled. Creates the `plugins:` map and
+ * `enabled` sequence if either is missing. Preserves comments and surrounding
+ * keys via parseDocument.
+ *
+ * Returns { changed, configPath, configCreated, alreadyEnabled }.
+ */
+async function addEnabledPlugin({ home, env, name } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("name is required");
+  }
+  const configPath = resolveHermesConfigPath({ home, env });
+
+  let raw = "";
+  let configCreated = false;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      configCreated = true;
+    } else {
+      throw err;
+    }
+  }
+
+  const doc = raw ? YAML.parseDocument(raw) : new YAML.Document({});
+  if (doc.errors && doc.errors.length > 0) {
+    const err = new Error(`config.yaml has YAML errors: ${doc.errors[0].message}`);
+    err.code = "HERMES_CONFIG_INVALID";
+    throw err;
+  }
+
+  // Ensure plugins is a Map.
+  let pluginsNode = doc.get("plugins", true);
+  if (pluginsNode === undefined || pluginsNode === null) {
+    doc.set("plugins", new YAML.YAMLMap());
+    pluginsNode = doc.get("plugins", true);
+  } else if (!(pluginsNode instanceof YAML.YAMLMap)) {
+    // Existing non-map value (string, list, scalar). Refuse so we never silently
+    // clobber user content. Caller should escalate to the user.
+    const err = new Error(
+      "plugins key in config.yaml is not a mapping; refusing to modify",
+    );
+    err.code = "HERMES_PLUGINS_NOT_MAP";
+    throw err;
+  }
+
+  // Ensure plugins.enabled is a Seq.
+  let enabledNode = pluginsNode.get("enabled", true);
+  if (enabledNode === undefined || enabledNode === null) {
+    pluginsNode.set("enabled", new YAML.YAMLSeq());
+    enabledNode = pluginsNode.get("enabled", true);
+  } else if (!(enabledNode instanceof YAML.YAMLSeq)) {
+    const err = new Error(
+      "plugins.enabled in config.yaml is not a sequence; refusing to modify",
+    );
+    err.code = "HERMES_PLUGINS_ENABLED_NOT_SEQ";
+    throw err;
+  }
+
+  // Idempotent add.
+  const current = enabledNode.toJSON() || [];
+  if (Array.isArray(current) && current.includes(name)) {
+    return {
+      changed: false,
+      configPath,
+      configCreated: false,
+      alreadyEnabled: true,
+    };
+  }
+  enabledNode.add(name);
+
+  const out = String(doc);
+  await writeFileAtomic(configPath, out);
+
+  return {
+    changed: true,
+    configPath,
+    configCreated,
+    alreadyEnabled: false,
+  };
+}
+
+/**
+ * Idempotently remove `name` from plugins.enabled. Cleans up empty container
+ * keys (`plugins.enabled` if it becomes [], and `plugins` if it becomes {}).
+ *
+ * Returns { changed, configPath, wasEnabled }.
+ */
+async function removeEnabledPlugin({ home, env, name } = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error("name is required");
+  }
+  const configPath = resolveHermesConfigPath({ home, env });
+
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return { changed: false, configPath, wasEnabled: false };
+    }
+    throw err;
+  }
+
+  const doc = YAML.parseDocument(raw);
+  if (doc.errors && doc.errors.length > 0) {
+    const err = new Error(`config.yaml has YAML errors: ${doc.errors[0].message}`);
+    err.code = "HERMES_CONFIG_INVALID";
+    throw err;
+  }
+
+  const pluginsNode = doc.get("plugins", true);
+  if (!(pluginsNode instanceof YAML.YAMLMap)) {
+    return { changed: false, configPath, wasEnabled: false };
+  }
+  const enabledNode = pluginsNode.get("enabled", true);
+  if (!(enabledNode instanceof YAML.YAMLSeq)) {
+    return { changed: false, configPath, wasEnabled: false };
+  }
+
+  // Find the index, since YAMLSeq.delete by name doesn't match by string value
+  // reliably across all node shapes. Iterating and matching the JSON value is
+  // the safe path.
+  const items = enabledNode.items;
+  let foundIndex = -1;
+  for (let i = 0; i < items.length; i += 1) {
+    const item = items[i];
+    const value = item && typeof item === "object" && "value" in item ? item.value : item;
+    if (value === name) {
+      foundIndex = i;
+      break;
+    }
+  }
+
+  if (foundIndex < 0) {
+    return { changed: false, configPath, wasEnabled: false };
+  }
+
+  enabledNode.delete(foundIndex);
+
+  // Clean up empty containers so we don't leave noise in user config.
+  if (enabledNode.items.length === 0) {
+    pluginsNode.delete("enabled");
+  }
+  if (pluginsNode.items.length === 0) {
+    doc.delete("plugins");
+  }
+
+  const out = String(doc);
+  await writeFileAtomic(configPath, out);
+
+  return { changed: true, configPath, wasEnabled: true };
+}
+
+module.exports = {
+  HERMES_CONFIG_FILENAME,
+  resolveHermesConfigPath,
+  probeEnabledPlugin,
+  addEnabledPlugin,
+  removeEnabledPlugin,
+};

package/src/lib/ops/audit-source.js

@@ -69,6 +69,19 @@ function runSourceAudit({
       throw new Error(`strategy.${key} is required`);
     }
   }
+
+  if (strategy.supportsAudit === false) {
+    return {
+      ok: false,
+      error: "audit-not-applicable",
+      source: strategy.id,
+      message:
+        `source=${strategy.id} does not support independent ground-truth audit ` +
+        "(data comes from the same plugin-ledger pipeline that feeds the DB)",
+      rows: [],
+      maxDriftPct: 0,
+    };
+  }
   if (!Number.isFinite(days) || days <= 0) {
     throw new Error(`days must be a positive number, got ${days}`);
   }

package/src/lib/ops/sources/hermes.js

@@ -24,6 +24,7 @@ const path = require("node:path");
 module.exports = {
   id: "hermes",
   displayName: "Hermes Plugin",
+  supportsAudit: false,
   sessionRoot({ home, env }) {
     const base = (env && env.VIBEUSAGE_HOME) || path.join(home, ".vibeusage");
     return path.join(base, "tracker");

package/src/templates/hermes-vibeusage-plugin/__init__.py

@@ -54,12 +54,12 @@ def post_api_request(session_id="", platform="", model="", provider="", api_mode
     record.update({
         "api_mode": str(api_mode or ""),
         "api_call_count": _safe_int(api_call_count),
-        "input_tokens": _safe_int(usage.get("input_tokens")),
-        "output_tokens": _safe_int(usage.get("output_tokens")),
-        "cache_read_tokens": _safe_int(usage.get("cache_read_tokens")),
-        "cache_write_tokens": _safe_int(usage.get("cache_write_tokens")),
-        "reasoning_tokens": _safe_int(usage.get("reasoning_tokens")),
-        "total_tokens": _safe_int(usage.get("total_tokens")),
+        "input_tokens": _safe_int(usage.get("input_tokens") or usage.get("input")),
+        "output_tokens": _safe_int(usage.get("output_tokens") or usage.get("output")),
+        "cache_read_tokens": _safe_int(usage.get("cache_read_tokens") or usage.get("cache_read")),
+        "cache_write_tokens": _safe_int(usage.get("cache_write_tokens") or usage.get("cache_write")),
+        "reasoning_tokens": _safe_int(usage.get("reasoning_tokens") or usage.get("reasoning")),
+        "total_tokens": _safe_int(usage.get("total_tokens") or usage.get("total")),
         "finish_reason": str(finish_reason or ""),
     })
     return _append_record(record)