vibeusage 0.3.1 → 0.3.3

package/README.md

@@ -209,7 +209,7 @@ graph LR
     C[Gemini CLI] -->|Session Logs| G
     D[Opencode] -->|SQLite DB| G
     E[Claude Code] -->|Hook Output| G
-    F[OpenClaw] -->|Session Plugin| G
+    F[OpenClaw] -->|Session Plugin → Sanitized Ledger| G
     G -->|AI Tokens| H{Core Relay}
     H --> I[VibeUsage Dashboard]
     H --> J[AI Analytics Engine]
@@ -236,7 +236,7 @@ graph LR
 
 1. AI CLI tools generate logs during usage
 2. Local `notify-handler` detects changes and triggers sync
-3. CLI incrementally parses logs and SQLite state, extracting whitelist token counts only
+3. CLI incrementally parses logs, SQLite state, and the OpenClaw sanitized ledger, extracting whitelist token counts only
 4. Data aggregated into 30-minute UTC buckets locally
 5. Batch upload to InsForge with idempotent deduplication
 6. Dashboard queries aggregated results for visualization
@@ -250,7 +250,7 @@ graph LR
 | **Gemini CLI** | `~/.gemini/tmp/**/chats/session-*.json` | `GEMINI_HOME` |
 | **Opencode** | `~/.local/share/opencode/opencode.db` (legacy `storage/message/**/*.json` fallback) | `OPENCODE_HOME` |
 | **Claude Code** | Parsed from hook output | - |
-| **OpenClaw** | Session plugin integration | - |
+| **OpenClaw** | Session plugin → local sanitized usage ledger | - |
 
 ## ⚙️ Configuration
 
@@ -279,6 +279,8 @@ graph LR
 
 </details>
 
+See also: [`docs/openclaw-integration.md`](docs/openclaw-integration.md) for the OpenClaw single-path accounting contract.
+
 ## 🔧 Troubleshooting
 
 <details>
@@ -380,8 +382,8 @@ This project uses **OpenSpec** for spec-driven development. Before making signif
 
 1. Read [`openspec/project.md`](openspec/project.md) for project conventions
 2. Check [`openspec/AGENTS.md`](openspec/AGENTS.md) for the full OpenSpec workflow
-3. Run `openspec list` to see active changes
-4. Run `openspec list --specs` to see existing specifications
+3. Run `npx openspec list` to see active changes
+4. Run `npx openspec list --specs` to see existing specifications
 
 See [CLAUDE.md](CLAUDE.md) for detailed guidelines.
 

package/README.zh-CN.md

@@ -143,7 +143,7 @@ npx vibeusage init [选项]
 | **Codex CLI** | `~/.codex/config.toml` | `notify` 钩子 |
 | **Every Code** | `~/.code/config.toml`（或 `CODE_HOME`） | `notify` 钩子 |
 | **Gemini CLI** | `~/.gemini/settings.json`（或 `GEMINI_HOME`） | `SessionEnd` 钩子 |
-| **Opencode** | 全局插件 | 消息解析器插件 |
+| **Opencode** | OpenCode 配置/插件 | SQLite-first 解析插件 |
 | **Claude Code** | `~/.claude/settings.json` | `Stop` + `SessionEnd` 钩子 |
 | **OpenClaw** | 安装时自动链接 | Session plugin（需要重启） |
 
@@ -207,9 +207,9 @@ graph LR
     A[Codex CLI] -->|Rollout 日志| G(Tracker CLI)
     B[Every Code] -->|Rollout 日志| G
     C[Gemini CLI] -->|会话日志| G
-    D[Opencode] -->|消息日志| G
+    D[Opencode] -->|SQLite DB| G
     E[Claude Code] -->|钩子输出| G
-    F[OpenClaw] -->|Gateway 钩子| G
+    F[OpenClaw] -->|Session Plugin → Sanitized Ledger| G
     G -->|AI Tokens| H{核心中继}
     H --> I[VibeUsage 控制台]
     H --> J[AI 分析引擎]
@@ -236,7 +236,7 @@ graph LR
 
 1. AI CLI 工具在使用过程中生成日志
 2. 本地 `notify-handler` 检测更改并触发同步
-3. CLI 增量解析日志，提取 token 计数（仅白名单字段）
+3. CLI 增量解析日志、SQLite 状态以及 OpenClaw 的本地脱敏 usage ledger，只提取白名单 token 计数
 4. 数据在本地聚合到 30 分钟 UTC 桶中
 5. 批量上传到 InsForge，带幂等去重
 6. 控制台查询聚合结果进行可视化
@@ -248,9 +248,9 @@ graph LR
 | **Codex CLI** | `~/.codex/sessions/**/rollout-*.jsonl` | `CODEX_HOME` |
 | **Every Code** | `~/.code/sessions/**/rollout-*.jsonl` | `CODE_HOME` |
 | **Gemini CLI** | `~/.gemini/tmp/**/chats/session-*.json` | `GEMINI_HOME` |
-| **Opencode** | `~/.opencode/messages/*.json` | - |
+| **Opencode** | `~/.local/share/opencode/opencode.db`（旧版 `storage/message/**/*.json` 仅作回退） | `OPENCODE_HOME` |
 | **Claude Code** | 从钩子输出解析 | - |
-| **OpenClaw** | Gateway 钩子集成 | - |
+| **OpenClaw** | Session plugin → 本地脱敏 usage ledger | - |
 
 ## ⚙️ 配置
 
@@ -278,6 +278,8 @@ graph LR
 
 </details>
 
+另见：[`docs/openclaw-integration.md`](docs/openclaw-integration.md)，其中说明了 OpenClaw 单一路径 accounting 合同。
+
 ## 🔧 故障排查
 
 <details>
@@ -374,8 +376,8 @@ npm run smoke
 
 1. 阅读 [`openspec/project.md`](openspec/project.md) 了解项目约定
 2. 查看 [`openspec/AGENTS.md`](openspec/AGENTS.md) 了解完整的 OpenSpec 工作流
-3. 运行 `openspec list` 查看活跃的更改
-4. 运行 `openspec list --specs` 查看现有规格
+3. 运行 `npx openspec list` 查看活跃的更改
+4. 运行 `npx openspec list --specs` 查看现有规格
 
 详见 [CLAUDE.md](CLAUDE.md) 了解详细指南。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "bin": {

package/src/commands/status.js

@@ -81,7 +81,6 @@ async function cmdStatus(argv = []) {
   const geminiProbe = probeByName.get("gemini");
   const opencodeProbe = probeByName.get("opencode");
   const openclawSessionProbe = probeByName.get("openclaw-session");
-  const openclawLegacyProbe = probeByName.get("openclaw-legacy");
   const opencodeDbPresent = Boolean((await safeStat(opencodeDbPath))?.isFile?.());
   const opencodeSqliteState =
     cursors?.opencodeSqlite && typeof cursors.opencodeSqlite === "object"
@@ -118,10 +117,6 @@ async function cmdStatus(argv = []) {
         descriptors.get("openclaw-session"),
         openclawSessionProbe,
       )}`,
-      `- OpenClaw hook (legacy): ${renderIntegrationStatus(
-        descriptors.get("openclaw-legacy"),
-        openclawLegacyProbe,
-      )}`,
       ...subscriptionLines,
       "",
     ]

package/src/commands/sync.js

@@ -13,9 +13,15 @@ const {
   parseClaudeIncremental,
   parseGeminiIncremental,
   parseOpencodeIncremental,
-  parseOpenclawIncremental,
+  normalizeHourlyState,
+  getHourlyBucket,
+  addTotals,
+  bucketKey,
+  enqueueTouchedBuckets,
+  toUtcHalfHourStart,
 } = require("../lib/rollout");
 const { drainQueueToCloud } = require("../lib/uploader");
+const { readOpenclawUsageLedger } = require("../lib/openclaw-usage-ledger");
 const { collectLocalSubscriptions } = require("../lib/subscriptions");
 const { createProgress, renderBar, formatNumber, formatBytes } = require("../lib/progress");
 const { syncHeartbeat } = require("../lib/vibeusage-api");
@@ -70,13 +76,6 @@ async function cmdSync(argv) {
     const opencodeStorageDir = path.join(opencodeHome, "storage");
     const opencodeDbPath = path.join(opencodeHome, "opencode.db");
 
-    // OpenClaw session-plugin integration: allow a plugin-triggered sync to request incremental parsing
-    // for a single session jsonl. We still parse all regular sources so model/source attribution stays
-    // complete (e.g. Kimi sessions).
-    const openclawSignal = opts.fromOpenclaw
-      ? resolveOpenclawSignal({ home, env: process.env })
-      : null;
-
     const sources = [
       { source: "codex", sessionsDir: path.join(codexHome, "sessions") },
       { source: "every-code", sessionsDir: path.join(codeHome, "sessions") },
@@ -93,10 +92,6 @@ async function cmdSync(argv) {
       }
     }
 
-    const openclawFiles = openclawSignal?.sessionFile
-      ? [{ path: openclawSignal.sessionFile, source: "openclaw" }]
-      : [];
-
     if (progress?.enabled) {
       progress.start(
         `Parsing ${renderBar(0)} 0/${formatNumber(rolloutFiles.length)} files | buckets 0`,
@@ -119,28 +114,13 @@ async function cmdSync(argv) {
       },
     });
 
-    let openclawResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-    if (openclawFiles.length > 0) {
-      // Only runs when explicitly triggered by OpenClaw session-plugin events.
-      openclawResult = await parseOpenclawIncremental({
-        sessionFiles: openclawFiles,
-        cursors,
-        queuePath,
-        projectQueuePath,
-        source: "openclaw",
-      });
-    }
-
-    const openclawFallback = await applyOpenclawTotalsFallback({
-      trackerDir,
-      signal: openclawSignal,
-      cursors,
-      queuePath,
-      projectQueuePath,
-    });
-    openclawResult.filesProcessed += openclawFallback.filesProcessed;
-    openclawResult.eventsAggregated += openclawFallback.eventsAggregated;
-    openclawResult.bucketsQueued += openclawFallback.bucketsQueued;
+    const openclawResult = opts.fromOpenclaw
+      ? await parseOpenclawSanitizedLedger({
+          trackerDir,
+          cursors,
+          queuePath,
+        })
+      : { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
 
     const claudeFiles = await listClaudeProjectFiles(claudeProjectsDir);
     let claudeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
@@ -456,153 +436,65 @@ function parseArgs(argv) {
 
 module.exports = { cmdSync };
 
-function normalizeString(value) {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-function resolveOpenclawSignal({ home, env } = {}) {
-  if (!env) return null;
-
-  const agentId = normalizeString(env.VIBEUSAGE_OPENCLAW_AGENT_ID);
-  const sessionId = normalizeString(env.VIBEUSAGE_OPENCLAW_PREV_SESSION_ID);
-  if (!agentId || !sessionId) return null;
-
-  const openclawHome =
-    normalizeString(env.VIBEUSAGE_OPENCLAW_HOME) || path.join(home || os.homedir(), ".openclaw");
-  const sessionFile = path.join(openclawHome, "agents", agentId, "sessions", `${sessionId}.jsonl`);
-
-  const prevTotals = {
-    totalTokens: normalizeNonNegativeInt(env.VIBEUSAGE_OPENCLAW_PREV_TOTAL_TOKENS),
-    inputTokens: normalizeNonNegativeInt(env.VIBEUSAGE_OPENCLAW_PREV_INPUT_TOKENS),
-    outputTokens: normalizeNonNegativeInt(env.VIBEUSAGE_OPENCLAW_PREV_OUTPUT_TOKENS),
-    model: normalizeString(env.VIBEUSAGE_OPENCLAW_PREV_MODEL),
-    updatedAt: normalizeIsoOrEpoch(env.VIBEUSAGE_OPENCLAW_PREV_UPDATED_AT),
-  };
-
-  return {
-    agentId,
-    sessionId,
-    sessionKey: normalizeString(env.VIBEUSAGE_OPENCLAW_SESSION_KEY),
-    openclawHome,
-    sessionFile,
-    prevTotals,
-  };
-}
+async function parseOpenclawSanitizedLedger({ trackerDir, cursors, queuePath }) {
+  const ledgerCursor =
+    cursors?.openclawLedger && typeof cursors.openclawLedger === "object"
+      ? cursors.openclawLedger
+      : {};
+  const offset = Math.max(0, Number(ledgerCursor.offset || 0));
+  const { events, endOffset } = await readOpenclawUsageLedger({ trackerDir, offset });
+
+  const hourlyState = normalizeHourlyState(cursors?.hourly);
+  const touchedBuckets = new Set();
+  let eventsAggregated = 0;
+
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    const bucketStart = toUtcHalfHourStart(event.emittedAt);
+    if (!bucketStart) continue;
+
+    const model =
+      typeof event.model === "string" && event.model.trim() ? event.model.trim() : "unknown";
+    const source =
+      typeof event.source === "string" && event.source.trim() ? event.source.trim() : "openclaw";
+    const delta = {
+      input_tokens: Math.max(0, Number(event.inputTokens || 0)),
+      cached_input_tokens: Math.max(0, Number(event.cachedInputTokens || 0)),
+      output_tokens: Math.max(0, Number(event.outputTokens || 0)),
+      reasoning_output_tokens: Math.max(0, Number(event.reasoningOutputTokens || 0)),
+      total_tokens: Math.max(0, Number(event.totalTokens || 0)),
+    };
+
+    if (
+      delta.input_tokens === 0 &&
+      delta.cached_input_tokens === 0 &&
+      delta.output_tokens === 0 &&
+      delta.reasoning_output_tokens === 0 &&
+      delta.total_tokens === 0
+    ) {
+      continue;
+    }
 
-async function applyOpenclawTotalsFallback({
-  trackerDir,
-  signal,
-  cursors,
-  queuePath,
-  projectQueuePath,
-}) {
-  const totalTokens = Number(signal?.prevTotals?.totalTokens || 0);
-  if (!trackerDir || !signal || totalTokens <= 0) {
-    return { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+    const bucket = getHourlyBucket(hourlyState, source, model, bucketStart);
+    addTotals(bucket.totals, delta);
+    touchedBuckets.add(bucketKey(source, model, bucketStart));
+    eventsAggregated += 1;
   }
 
-  const sessionKey = `${signal.agentId}:${signal.sessionId}`;
-  const statePath = path.join(trackerDir, "openclaw.fallback.state.json");
-  const fallbackFilePath = path.join(trackerDir, "openclaw.fallback.jsonl");
-  const state = (await readJson(statePath)) || { version: 1, sessions: {} };
-  const sessions = state.sessions && typeof state.sessions === "object" ? state.sessions : {};
-  const prev =
-    sessions[sessionKey] && typeof sessions[sessionKey] === "object" ? sessions[sessionKey] : null;
-
-  const current = {
-    totalTokens: normalizeNonNegativeInt(signal?.prevTotals?.totalTokens) || 0,
-    inputTokens: normalizeNonNegativeInt(signal?.prevTotals?.inputTokens) || 0,
-    outputTokens: normalizeNonNegativeInt(signal?.prevTotals?.outputTokens) || 0,
-    model: normalizeString(signal?.prevTotals?.model) || "unknown",
-    updatedAt: normalizeIsoOrEpoch(signal?.prevTotals?.updatedAt) || new Date().toISOString(),
-    seenAt: new Date().toISOString(),
+  const bucketsQueued = await enqueueTouchedBuckets({ queuePath, hourlyState, touchedBuckets });
+  hourlyState.updatedAt = new Date().toISOString();
+  cursors.hourly = hourlyState;
+  cursors.openclawLedger = {
+    version: 1,
+    offset: endOffset,
+    updatedAt: new Date().toISOString(),
   };
 
-  let deltaTotal = current.totalTokens;
-  let deltaInput = current.inputTokens;
-  let deltaOutput = current.outputTokens;
-  if (prev) {
-    deltaTotal = Math.max(
-      0,
-      current.totalTokens - (normalizeNonNegativeInt(prev.totalTokens) || 0),
-    );
-    deltaInput = Math.max(
-      0,
-      current.inputTokens - (normalizeNonNegativeInt(prev.inputTokens) || 0),
-    );
-    deltaOutput = Math.max(
-      0,
-      current.outputTokens - (normalizeNonNegativeInt(prev.outputTokens) || 0),
-    );
-  }
-
-  if (deltaTotal > 0 && deltaInput + deltaOutput === 0) {
-    deltaInput = deltaTotal;
-  }
-
-  sessions[sessionKey] = current;
-  state.version = 1;
-  state.sessions = sessions;
-
-  if (deltaTotal <= 0) {
-    await writeJson(statePath, state);
-    return { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
-  }
-
-  await ensureDir(path.dirname(fallbackFilePath));
-  const syntheticMessage = {
-    type: "message",
-    timestamp: current.updatedAt,
-    message: {
-      role: "assistant",
-      model: current.model,
-      usage: {
-        input: deltaInput,
-        output: deltaOutput,
-        cacheRead: 0,
-        cacheWrite: 0,
-        totalTokens: deltaTotal,
-      },
-    },
+  return {
+    filesProcessed: endOffset > offset ? 1 : 0,
+    eventsAggregated,
+    bucketsQueued,
   };
-  await fs.appendFile(fallbackFilePath, `${JSON.stringify(syntheticMessage)}\n`, "utf8");
-  await writeJson(statePath, state);
-
-  return parseOpenclawIncremental({
-    sessionFiles: [{ path: fallbackFilePath, source: "openclaw" }],
-    cursors,
-    queuePath,
-    projectQueuePath,
-    source: "openclaw",
-  });
-}
-
-function normalizeNonNegativeInt(value) {
-  const n = Number(value);
-  if (!Number.isFinite(n) || n < 0) return null;
-  return Math.floor(n);
-}
-
-function normalizeIsoOrEpoch(value) {
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (trimmed.length > 0 && !Number.isNaN(Date.parse(trimmed))) return trimmed;
-    const numeric = Number(trimmed);
-    if (Number.isFinite(numeric) && numeric > 0) {
-      const ms = numeric < 1e12 ? Math.floor(numeric * 1000) : Math.floor(numeric);
-      const iso = new Date(ms).toISOString();
-      if (!Number.isNaN(Date.parse(iso))) return iso;
-    }
-  }
-
-  const n = Number(value);
-  if (!Number.isFinite(n) || n <= 0) return null;
-  const ms = n < 1e12 ? Math.floor(n * 1000) : Math.floor(n);
-  const dt = new Date(ms);
-  if (Number.isNaN(dt.getTime())) return null;
-  return dt.toISOString();
 }
 
 async function safeStatSize(p) {

package/src/commands/uninstall.js

@@ -93,17 +93,6 @@ async function cmdUninstall(argv) {
         unreadableText: (result) =>
           `- OpenClaw session plugin: skipped (${result.detail || "openclaw config unreadable"})`,
       }),
-      renderHookLine({
-        exists: true,
-        result: resultByName.get("openclaw-legacy"),
-        missingText: "- OpenClaw hook (legacy): skipped (openclaw config not found)",
-        removedText: (result) =>
-          `- OpenClaw hook (legacy) removed: ${result.detail || result.openclawConfigPath || "unknown"}`,
-        noChangeText: "- OpenClaw hook (legacy): no change",
-        skippedText: "- OpenClaw hook (legacy): no change",
-        unreadableText: (result) =>
-          `- OpenClaw hook (legacy): skipped (${result.detail || "openclaw config unreadable"})`,
-      }),
       opts.purge ? `- Purged: ${path.join(home, ".vibeusage")}` : "- Purge: skipped (use --purge)",
       "",
     ].join("\n"),

package/src/lib/diagnostics.js

@@ -61,7 +61,6 @@ async function collectTrackerDiagnostics({
   const geminiProbe = probeByName.get("gemini");
   const opencodeProbe = probeByName.get("opencode");
   const openclawSessionProbe = probeByName.get("openclaw-session");
-  const openclawLegacyProbe = probeByName.get("openclaw-legacy");
 
   const codexNotify = Array.isArray(codexProbe?.currentNotify)
     ? codexProbe.currentNotify.map((value) => redactValue(value, home))
@@ -156,14 +155,6 @@ async function collectTrackerDiagnostics({
         typeof openclawSessionProbe?.detail === "string"
           ? redactError(openclawSessionProbe.detail, home)
           : null,
-      openclaw_hook_status: openclawLegacyProbe?.status || "unknown",
-      openclaw_hook_configured: Boolean(openclawLegacyProbe?.configured),
-      openclaw_hook_linked: Boolean(openclawLegacyProbe?.linked),
-      openclaw_hook_enabled: Boolean(openclawLegacyProbe?.enabled),
-      openclaw_hook_detail:
-        typeof openclawLegacyProbe?.detail === "string"
-          ? redactError(openclawLegacyProbe.detail, home)
-          : null,
     },
     upload: {
       last_success_at: lastSuccessAt,

package/src/lib/doctor.js

@@ -313,8 +313,7 @@ function buildDiagnosticsChecks(diagnostics) {
     notify.claude_hook_configured ||
     notify.gemini_hook_configured ||
     notify.opencode_plugin_configured ||
-    notify.openclaw_session_plugin_configured ||
-    notify.openclaw_hook_configured,
+    notify.openclaw_session_plugin_configured,
   );
 
   checks.push({
@@ -338,19 +337,6 @@ function buildDiagnosticsChecks(diagnostics) {
     });
   }
 
-  if (notify.openclaw_hook_status === "unreadable") {
-    checks.push({
-      id: "notify.openclaw_hook",
-      status: "warn",
-      detail: "OpenClaw hook config unreadable",
-      critical: false,
-      meta: {
-        status: notify.openclaw_hook_status,
-        detail: notify.openclaw_hook_detail || null,
-      },
-    });
-  }
-
   const uploadError = diagnostics?.upload?.last_error || null;
   checks.push({
     id: "upload.last_error",

package/src/lib/integrations/context.js

@@ -8,7 +8,6 @@ const {
   buildGeminiHookCommand,
 } = require("../gemini-config");
 const { resolveOpencodeConfigDir } = require("../opencode-config");
-const { resolveOpenclawHookPaths } = require("../openclaw-hook");
 const { resolveOpenclawSessionPluginPaths } = require("../openclaw-session-plugin");
 const { resolveTrackerPaths } = require("../tracker-paths");
 
@@ -63,11 +62,6 @@ async function createIntegrationContext({
       trackerDir: resolvedTrackerPaths.trackerDir,
       env,
     }),
-    openclawLegacy: resolveOpenclawHookPaths({
-      home,
-      trackerDir: resolvedTrackerPaths.trackerDir,
-      env,
-    }),
   };
 }
 

package/src/lib/integrations/index.js

@@ -5,7 +5,6 @@ const claude = require("./claude");
 const gemini = require("./gemini");
 const opencode = require("./opencode");
 const openclawSession = require("./openclaw-session");
-const openclawLegacy = require("./openclaw-legacy");
 
 const INTEGRATIONS = [
   codex,
@@ -14,7 +13,6 @@ const INTEGRATIONS = [
   gemini,
   opencode,
   openclawSession,
-  openclawLegacy,
 ];
 
 function listIntegrations() {