@optimuslabs/harness-map-staging 1.5.16

package/dist/log_config_files/collection/hermes_token_usage_collector.js

@@ -0,0 +1,241 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { execSqlite3, resolveSqlite3Binary } from '../runtime/sqlite_binary.js';
+/**
+ * Session / token usage / model / version aggregator for Hermes Agent (Nous Research).
+ *
+ * Hermes keeps all state under ~/.hermes/. Three sources feed this aggregate, each read
+ * narrowly to avoid ever touching credential material:
+ *   - state.db (SQLite) `sessions` table — real per-session model + token columns
+ *     (input_tokens, output_tokens, reasoning_tokens, cache_read_tokens) plus real USD cost
+ *     columns (actual_cost_usd, falling back to estimated_cost_usd — Hermes computes this
+ *     itself via a provider pricing-table lookup, cost_source="provider_models_api" on a real
+ *     install). started_at is a Unix epoch *seconds* REAL column, bounded to the last 30 days.
+ *   - config.yaml — only the top-level `model` key is extracted: the plain-string form
+ *     (`model: "name"`), or the block form's `default`/`provider`/`base_url` sub-keys
+ *     (`model:\n  default: "name"\n  provider: openrouter\n  base_url: ''`). config.yaml can
+ *     hold literal provider API keys under `providers:`, so this is a scoped line-scan, never a
+ *     full YAML parse — `provider`/`base_url` live directly under `model:`, not `providers:`,
+ *     so reading them carries no credential risk.
+ *   - auth.json — only the top-level `active_provider` key (e.g. "nous") is read; the
+ *     per-provider blocks under `providers:` hold OAuth/API-key secrets and are never
+ *     touched. "nous" is Nous Portal OAuth; anything else is a traditional API-key
+ *     provider (see hermes_cli/auth.py's ProviderConfig registry).
+ *
+ * There is no on-disk record of email/org/plan — those only exist inside the live OAuth
+ * access_token's JWT claims (the actual bearer credential, not a side identity token like
+ * Codex's id_token), so this collector does not decode it. Version comes from the bundled
+ * source checkout's hermes_cli/__init__.py (best-effort; empty string if unavailable).
+ */
+const TOKEN_USAGE_RECENCY_DAYS = 30;
+const TOKEN_USAGE_FILE_TYPE = 'hermes_token_usage';
+const ROW_SEP = '\x1e';
+const FIELD_SEP = '\x1f';
+const PROVIDER_NOUS = 'nous';
+const AUTH_NOUS_OAUTH = 'nous_oauth';
+const AUTH_API_KEY = 'api_key';
+function emptyTotals() {
+    return { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0 };
+}
+function num(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const n = parseFloat(value);
+        return Number.isFinite(n) ? n : 0;
+    }
+    return 0;
+}
+function querySqlite(sqlite3, dbPath, sql) {
+    try {
+        return execSqlite3(sqlite3, ['-readonly', '-noheader', dbPath], `.timeout 5000\n${sql}\n`);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract a plain YAML scalar value, stripping quotes and a trailing inline comment.
+ * A quoted value's content ends at the matching close-quote (anything after, including a
+ * comment, is discarded). An unquoted value's comment starts at a `#` preceded by whitespace
+ * or at the start of the string (a bare `#` glued to non-space text is part of the value, per
+ * the YAML spec's plain-scalar comment rule).
+ */
+function stripYamlScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"')) {
+        const end = trimmed.indexOf('"', 1);
+        return end !== -1 ? trimmed.slice(1, end) : trimmed.slice(1);
+    }
+    if (trimmed.startsWith("'")) {
+        const end = trimmed.indexOf("'", 1);
+        return end !== -1 ? trimmed.slice(1, end) : trimmed.slice(1);
+    }
+    const commentIdx = trimmed.search(/(?:^|\s)#/);
+    return (commentIdx === -1 ? trimmed : trimmed.slice(0, commentIdx)).trim();
+}
+const EMPTY_MODEL_CONFIG = { model: '', provider: '', baseUrl: '' };
+/**
+ * Scoped read of config.yaml's top-level `model` key only. Handles both the plain-string
+ * form (`model: "name"`, which carries no provider/base_url) and the block form
+ * (`model:\n  default: "name"\n  provider: openrouter\n  base_url: ''`). Never parses or
+ * returns any other key — config.yaml's `providers:` block can carry literal API keys, so this
+ * deliberately avoids a full YAML parse.
+ */
+function readModelConfig(home) {
+    let text;
+    try {
+        text = readFileSync(join(home, '.hermes', 'config.yaml'), 'utf8');
+    }
+    catch {
+        return EMPTY_MODEL_CONFIG;
+    }
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^model:\s*(.*)$/);
+        if (!m)
+            continue;
+        const inline = stripYamlScalar(m[1]);
+        if (inline)
+            return { ...EMPTY_MODEL_CONFIG, model: inline };
+        // Block form: scan indented lines immediately below for default/provider/base_url —
+        // order isn't fixed, so keep scanning until the block dedents rather than stopping at the
+        // first match.
+        const result = { ...EMPTY_MODEL_CONFIG };
+        for (let j = i + 1; j < lines.length; j++) {
+            const next = lines[j];
+            if (next.trim() === '')
+                continue;
+            if (/^\S/.test(next))
+                break; // dedented — end of the `model:` block
+            const dm = next.match(/^\s+default:\s*(.*)$/);
+            if (dm) {
+                result.model = stripYamlScalar(dm[1]);
+                continue;
+            }
+            const pm = next.match(/^\s+provider:\s*(.*)$/);
+            if (pm) {
+                result.provider = stripYamlScalar(pm[1]);
+                continue;
+            }
+            const bm = next.match(/^\s+base_url:\s*(.*)$/);
+            if (bm) {
+                result.baseUrl = stripYamlScalar(bm[1]);
+            }
+        }
+        return result;
+    }
+    return EMPTY_MODEL_CONFIG;
+}
+/** Scoped read of auth.json's top-level `active_provider` key only — never the `providers` block. */
+function readActiveProvider(home) {
+    try {
+        const raw = JSON.parse(readFileSync(join(home, '.hermes', 'auth.json'), 'utf8'));
+        return typeof raw.active_provider === 'string' ? raw.active_provider : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Best-effort CLI version from the bundled source checkout; empty string if unavailable. */
+function readHermesVersion(home) {
+    try {
+        const text = readFileSync(join(home, '.hermes', 'hermes-agent', 'hermes_cli', '__init__.py'), 'utf8');
+        const m = text.match(/^__version__\s*=\s*["']([^"']+)["']/m);
+        return m ? m[1] : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Aggregate Hermes session count / token usage / models / version / active provider.
+ * Returns a single-element array (one per-machine aggregate) or [] when no usable DB exists.
+ */
+function collectHermesTokenUsage(home = homedir()) {
+    const dbPath = join(home, '.hermes', 'state.db');
+    if (!existsSync(dbPath))
+        return [];
+    const sqlite3 = resolveSqlite3Binary();
+    if (!sqlite3)
+        return [];
+    // started_at is Unix epoch *seconds* (REAL), unlike the epoch-ms convention elsewhere.
+    const cutoffSeconds = Math.floor(Date.now() / 1000) - TOKEN_USAGE_RECENCY_DAYS * 24 * 60 * 60;
+    const usageRaw = querySqlite(sqlite3, dbPath, `SELECT
+       COALESCE(model, 'default') || char(31) ||
+       COUNT(*) || char(31) ||
+       COALESCE(SUM(input_tokens), 0) || char(31) ||
+       COALESCE(SUM(output_tokens), 0) || char(31) ||
+       COALESCE(SUM(reasoning_tokens), 0) || char(31) ||
+       COALESCE(SUM(cache_read_tokens), 0) || char(31) ||
+       COALESCE(SUM(COALESCE(actual_cost_usd, estimated_cost_usd, 0)), 0) || char(30)
+     FROM sessions
+     WHERE started_at >= ${cutoffSeconds}
+     GROUP BY model;`);
+    const models = new Set();
+    const totals = emptyTotals();
+    const modelTokenSplit = {};
+    let sessionCount = 0;
+    let cost = 0;
+    if (usageRaw) {
+        for (const row of usageRaw.split(ROW_SEP)) {
+            const trimmed = row.trim();
+            if (!trimmed)
+                continue;
+            const fields = trimmed.split(FIELD_SEP);
+            if (fields.length < 7)
+                continue;
+            const [model, count, input, output, reasoning, cacheRead, modelCost] = fields;
+            const cnt = num(count);
+            sessionCount += cnt;
+            if (model)
+                models.add(model);
+            const modelInput = num(input);
+            // reasoning_tokens folds into output_tokens — TokenTotals has no separate reasoning
+            // field (matches Codex's reasoning_output_tokens fold-in), so a reasoning/non-reasoning
+            // split isn't distinguishable downstream.
+            const modelOutput = num(output) + num(reasoning);
+            const modelCacheRead = num(cacheRead);
+            totals.input_tokens += modelInput;
+            totals.output_tokens += modelOutput;
+            totals.cache_read_input_tokens += modelCacheRead;
+            cost += num(modelCost);
+            const modelSum = modelInput + modelOutput + modelCacheRead;
+            if (model && modelSum > 0) {
+                modelTokenSplit[model] = (modelTokenSplit[model] ?? 0) + modelSum;
+            }
+        }
+    }
+    const modelConfig = readModelConfig(home);
+    const activeProvider = readActiveProvider(home);
+    const version = readHermesVersion(home);
+    const authMethod = activeProvider
+        ? activeProvider === PROVIDER_NOUS
+            ? AUTH_NOUS_OAUTH
+            : AUTH_API_KEY
+        : '';
+    if (sessionCount === 0 && !modelConfig.model && !activeProvider)
+        return [];
+    return [
+        {
+            file_type: TOKEN_USAGE_FILE_TYPE,
+            file_path: dbPath,
+            raw_content: {
+                version,
+                session_count: sessionCount,
+                models: [...models].sort(),
+                model_token_split: modelTokenSplit,
+                configured_model: modelConfig.model,
+                configured_model_provider: modelConfig.provider,
+                configured_model_base_url: modelConfig.baseUrl,
+                window_days: TOKEN_USAGE_RECENCY_DAYS,
+                totals,
+                cost,
+                active_provider: activeProvider,
+                auth_method: authMethod,
+            },
+        },
+    ];
+}
+export { collectHermesTokenUsage, TOKEN_USAGE_RECENCY_DAYS, TOKEN_USAGE_FILE_TYPE };

package/dist/log_config_files/collection/mcp_tool_collector.js

@@ -0,0 +1,106 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readJSONFile } from '../readers/file_readers.js';
+import { normalizePathSkipPrefixes } from '../paths/pattern_resolver.js';
+import { getCursorProjectsPath } from '../paths/path_constants_helpers.js';
+import { isInternalCursorWorkspaceSlug } from './cursor_project_mcp_collector.js';
+import { isStaleCursorProjectWorkspace } from './cursor_project_workspace_activity.js';
+import { readVscdbItemTableJson } from '../readers/vscdb_reader.js';
+/**
+ * Read workspaceMetadata.entries from the Cursor global state.vscdb and emit one
+ * cursor_workspace_vscdb ConfigFileData per workspace entry.
+ *
+ * Cursor maintains a canonical mapping of workspace hash → display path in the global
+ * state.vscdb under "workspaceMetadata.entries". Each entry has:
+ *   { workspaceId: "<hash>", displayPath: "~/my-project", folderUri: "file:///Users/..." }
+ *
+ * The per-workspace workspaceStorage/<hash>/state.vscdb holds cursor/disabledMcpServers.
+ * Together they give us: which servers are disabled per workspace + a human-readable label.
+ */
+function collectWorkspaceVscdbs(spec, home = homedir()) {
+    if (!spec.global_vscdb_path_segments?.length || !spec.global_workspace_list_key) {
+        return [];
+    }
+    const globalDbPath = join(home, ...spec.global_vscdb_path_segments);
+    if (!existsSync(globalDbPath))
+        return [];
+    const globalResult = readVscdbItemTableJson(globalDbPath, spec.global_workspace_list_key);
+    if (!globalResult)
+        return [];
+    const rawValue = globalResult[spec.global_workspace_list_key];
+    // The stored value is {"entries": [...]}; unwrap it.
+    const entries = Array.isArray(rawValue)
+        ? rawValue
+        : Array.isArray(rawValue?.entries)
+            ? rawValue.entries
+            : [];
+    if (!entries.length)
+        return [];
+    const workspaceStoragePath = join(home, ...spec.workspace_storage_path_segments);
+    const output = [];
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        const workspaceId = typeof e.workspaceId === 'string' ? e.workspaceId : null;
+        if (!workspaceId)
+            continue;
+        const dbPath = join(workspaceStoragePath, workspaceId, spec.vscdb_filename);
+        if (!existsSync(dbPath))
+            continue;
+        const perWorkspaceResult = readVscdbItemTableJson(dbPath, spec.item_table_key);
+        const disabled = perWorkspaceResult?.[spec.item_table_key];
+        const rawContent = {
+            [spec.item_table_key]: Array.isArray(disabled) ? disabled : [],
+        };
+        if (typeof e.displayPath === 'string')
+            rawContent['displayPath'] = e.displayPath;
+        if (typeof e.folderUri === 'string')
+            rawContent['folderUri'] = e.folderUri;
+        rawContent['workspaceId'] = workspaceId;
+        output.push({
+            file_type: spec.file_type,
+            file_path: `${dbPath}#${spec.item_table_key}`,
+            raw_content: rawContent,
+        });
+    }
+    return output;
+}
+function collectMcpToolFiles(pathSkipPrefixes = [], constants) {
+    const result = [];
+    const skipPrefixes = normalizePathSkipPrefixes(pathSkipPrefixes);
+    const home = homedir();
+    const cursorProjectsPath = getCursorProjectsPath(home, constants);
+    try {
+        if (!existsSync(cursorProjectsPath))
+            return result;
+        for (const projectDir of readdirSync(cursorProjectsPath, { withFileTypes: true }).filter((d) => d.isDirectory())) {
+            if (skipPrefixes.some((p) => projectDir.name.startsWith(p)))
+                continue;
+            if (isInternalCursorWorkspaceSlug(projectDir.name))
+                continue;
+            const projectPath = join(cursorProjectsPath, projectDir.name);
+            if (isStaleCursorProjectWorkspace(projectPath))
+                continue;
+            const mcpsPath = join(projectPath, 'mcps');
+            if (!existsSync(mcpsPath))
+                continue;
+            for (const serverDir of readdirSync(mcpsPath, { withFileTypes: true }).filter((d) => d.isDirectory())) {
+                const toolsPath = join(mcpsPath, serverDir.name, 'tools');
+                if (!existsSync(toolsPath))
+                    continue;
+                for (const toolFile of readdirSync(toolsPath).filter((n) => n.endsWith('.json'))) {
+                    const content = readJSONFile(join(toolsPath, toolFile));
+                    if (content)
+                        result.push({ file_type: 'mcp_tool', file_path: `${projectDir.name}/mcps/${serverDir.name}/tools/${toolFile}`, raw_content: content });
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.warn('Error collecting MCP tool files:', error instanceof Error ? error.message : String(error));
+    }
+    return result;
+}
+export { collectMcpToolFiles, collectWorkspaceVscdbs };

package/dist/log_config_files/collection/metadata_merge.js

@@ -0,0 +1,43 @@
+/** When several install/log paths exist for one agent, keep a single metadata row (newest mtime). */
+const METADATA_COLLAPSE_BY_FILE_TYPE = new Set(['opencode_presence', 'opencode_log']);
+function metadataLastModifiedMs(entry) {
+    const raw = entry.raw_content;
+    if (!raw || typeof raw !== 'object')
+        return 0;
+    const lm = raw.last_modified;
+    if (typeof lm !== 'string')
+        return 0;
+    const ms = Date.parse(lm);
+    return Number.isFinite(ms) ? ms : 0;
+}
+/**
+ * Collapse multiple metadata uploads of the same file_type to one row: highest last_modified wins.
+ */
+function collapseMetadataByFileType(files) {
+    const passthrough = [];
+    const groups = new Map();
+    for (const f of files) {
+        if (f.collect_style === 'metadata' && METADATA_COLLAPSE_BY_FILE_TYPE.has(f.file_type)) {
+            const list = groups.get(f.file_type) ?? [];
+            list.push(f);
+            groups.set(f.file_type, list);
+        }
+        else {
+            passthrough.push(f);
+        }
+    }
+    const merged = [...passthrough];
+    for (const [, list] of groups) {
+        if (list.length === 0)
+            continue;
+        let best = list[0];
+        for (let i = 1; i < list.length; i++) {
+            if (metadataLastModifiedMs(list[i]) > metadataLastModifiedMs(best)) {
+                best = list[i];
+            }
+        }
+        merged.push(best);
+    }
+    return merged;
+}
+export { collapseMetadataByFileType, METADATA_COLLAPSE_BY_FILE_TYPE };

package/dist/log_config_files/collection/openclaw_helpers.js

@@ -0,0 +1,55 @@
+import { join } from 'node:path';
+import { readJSONFile } from '../readers/file_readers.js';
+import { getByPath } from './enrichment_helpers.js';
+function getInstallsEntries(raw, recipe) {
+    const installsPath = recipe.installs_path ?? recipe.installs_path_fallback;
+    if (!installsPath)
+        return [];
+    let installs = getByPath(raw, installsPath);
+    if (!installs && recipe.installs_path_fallback && recipe.installs_path_fallback !== installsPath) {
+        installs = getByPath(raw, recipe.installs_path_fallback);
+    }
+    if (!installs)
+        return [];
+    if (Array.isArray(installs)) {
+        return installs.filter((e) => typeof e === 'object' && e !== null);
+    }
+    if (typeof installs === 'object' && installs !== null) {
+        return Object.values(installs).filter((e) => typeof e === 'object' && e !== null);
+    }
+    return [];
+}
+function resolvePathFromTemplate(entry, pathTemplate) {
+    const installPath = entry.installPath?.trim() ?? '';
+    const sourcePath = entry.sourcePath?.trim() ?? '';
+    return pathTemplate
+        .replace(/\{\{installPath\}\}/g, installPath)
+        .replace(/\{\{sourcePath\}\}/g, sourcePath);
+}
+/**
+ * For file types whose enrich recipe has derived_files: from each install entry in raw,
+ * resolve path from path_template ({{installPath}}, {{sourcePath}}), read file, push with recipe file_type.
+ * Driven by backend FILE_TYPE_ENRICHMENT.derived_files; no openclaw-specific logic here.
+ */
+function pushDerivedFilesFromRecipe(raw, configFiles, recipe) {
+    const derived = recipe.derived_files;
+    if (!derived?.length)
+        return;
+    const entries = getInstallsEntries(raw, recipe);
+    for (const entry of entries) {
+        for (const spec of derived) {
+            let path = resolvePathFromTemplate(entry, spec.path_template).replace(/\/+/g, '/').trim();
+            if (!path && spec.path_template_fallback) {
+                path = resolvePathFromTemplate(entry, spec.path_template_fallback).replace(/\/+/g, '/').trim();
+            }
+            if (!path)
+                continue;
+            const fullPath = path.startsWith('/') ? path : join(process.cwd(), path);
+            const content = readJSONFile(fullPath);
+            if (content !== null) {
+                configFiles.push({ file_type: spec.file_type, file_path: fullPath, raw_content: content });
+            }
+        }
+    }
+}
+export { pushDerivedFilesFromRecipe };

package/dist/log_config_files/collection/openclaw_token_usage_collector.js

@@ -0,0 +1,223 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/**
+ * Session / token usage / model / version aggregator for OpenClaw
+ * (github.com/openclaw/openclaw — a multi-channel AI gateway, unrelated to Hermes/Nous Research
+ * despite Hermes shipping a `hermes claw migrate` path to import from it).
+ *
+ * OpenClaw keeps a session store per agent at
+ * ~/.openclaw/agents/<agentId>/sessions/sessions.json — a sessionKey -> SessionEntry map
+ * (see docs/reference/session-management-compaction.md in the openclaw package: "Session
+ * store schema"). SessionEntry carries both routing/identity fields (displayName, channel,
+ * groupChannel, groupId, lastAccountId, lastChannel, lastThreadId, lastTo, deliveryContext,
+ * origin — who the session's conversation partner was) and numeric/model fields (inputTokens,
+ * outputTokens, cacheRead, cacheWrite, totalTokens, model, modelProvider). This collector reads
+ * ONLY the numeric/model fields — the existing openclaw_sessions file type registration already
+ * treats this file's content as sensitive (collect_style="metadata", path+mtime only), so the
+ * routing/identity fields are never touched or returned here.
+ *
+ * Version comes from a scoped read of openclaw.json's top-level `meta.lastTouchedVersion` key
+ * only — never any other key (openclaw.json's other sections can carry messaging/provider
+ * settings).
+ *
+ * Auth method comes from a scoped read of openclaw.json's `auth.profiles.*` entries — each
+ * profile is `{provider, mode}` (e.g. `{"provider": "anthropic", "mode": "api_key"}`); we read
+ * only those two keys, never any credential material (profiles carry no token/key fields to
+ * begin with). Exposed per-provider so the extractor can match it against the provider actually
+ * observed in session usage.
+ *
+ * Routing config comes from two more scoped reads of openclaw.json:
+ *   - `agents.defaults.model.primary` (format `"provider/model"`) — the configured provider id,
+ *     same precedence convention as other agents' `"provider/model"` pinning.
+ *   - `models.providers.<id>` tables — `baseUrl`/`auth` (a strategy string like `"aws-sdk"`)
+ *     only, never `apiKey`, `headers`, or the `models` catalog (this is a DIFFERENT top-level
+ *     key than `auth.profiles` above; a real install can have one without the other).
+ *
+ * Only checks ~/.openclaw (the canonical root); the moltbot/clawdbot compatible-fork roots
+ * tracked by the presence/log file types are not covered here.
+ */
+const TOKEN_USAGE_RECENCY_DAYS = 30;
+const TOKEN_USAGE_FILE_TYPE = 'openclaw_token_usage';
+function emptyTotals() {
+    return { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0 };
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function str(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/** Every ~/.openclaw/agents/<agentId>/sessions/sessions.json that exists. */
+function discoverSessionsStores(openclawDir) {
+    const agentsDir = join(openclawDir, 'agents');
+    let entries;
+    try {
+        entries = readdirSync(agentsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const storePath = join(agentsDir, entry.name, 'sessions', 'sessions.json');
+        if (existsSync(storePath))
+            out.push(storePath);
+    }
+    return out;
+}
+/**
+ * Scoped read of one sessions.json store: only numeric/model fields per SessionEntry, bounded
+ * to the recency window. See the module docstring for the fields this deliberately never reads.
+ */
+function readSessionsStore(storePath, cutoffMs, acc) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(storePath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    if (!raw || typeof raw !== 'object')
+        return;
+    for (const value of Object.values(raw)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const entry = value;
+        // updatedAt is Unix epoch *milliseconds*, matching cutoffMs below (unlike Hermes's
+        // started_at, which is epoch seconds). Confirmed against a real sessions.json: a raw
+        // value of 1772443946772 resolves to 2026-03-02T09:32:26.772Z, the correct magnitude
+        // for epoch-ms — a seconds value at that date would be ~10 digits, not 13.
+        if (num(entry.updatedAt) < cutoffMs)
+            continue;
+        const sessionId = str(entry.sessionId);
+        if (sessionId)
+            acc.sessionIds.add(sessionId);
+        const model = str(entry.model);
+        const provider = str(entry.modelProvider);
+        if (model)
+            acc.models.add(model);
+        if (provider)
+            acc.providers.add(provider);
+        const input = num(entry.inputTokens);
+        const output = num(entry.outputTokens);
+        const cacheRead = num(entry.cacheRead);
+        acc.totals.input_tokens += input;
+        acc.totals.output_tokens += output;
+        acc.totals.cache_read_input_tokens += cacheRead;
+        const sum = input + output + cacheRead;
+        if (model && sum > 0) {
+            acc.modelTokenSplit[model] = (acc.modelTokenSplit[model] ?? 0) + sum;
+        }
+    }
+}
+/** Parses openclaw.json once; both readVersion and readAuthModesByProvider derive from this. */
+function parseOpenclawJson(openclawDir) {
+    try {
+        return JSON.parse(readFileSync(join(openclawDir, 'openclaw.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Scoped read of openclaw.json's top-level `meta.lastTouchedVersion` key only. */
+function readVersion(raw) {
+    const meta = raw?.meta;
+    return meta && typeof meta === 'object'
+        ? str(meta.lastTouchedVersion)
+        : '';
+}
+/**
+ * Scoped read of openclaw.json's `auth.profiles` — provider + mode only, never credentials
+ * (the profiles carry no token/key fields). Returns a provider -> mode map (e.g.
+ * `{"anthropic": "api_key"}`); a provider with multiple profiles keeps the last one read.
+ */
+function readAuthModesByProvider(raw) {
+    const auth = raw?.auth;
+    const profiles = auth && typeof auth === 'object' ? auth.profiles : undefined;
+    const out = {};
+    if (profiles && typeof profiles === 'object') {
+        for (const value of Object.values(profiles)) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const entry = value;
+            const provider = str(entry.provider);
+            const mode = str(entry.mode);
+            if (provider && mode)
+                out[provider] = mode;
+        }
+    }
+    return out;
+}
+/** Scoped read of openclaw.json's `agents.defaults.model.primary` key only (format "provider/model"). */
+function readPrimaryModelProvider(raw) {
+    const agents = raw?.agents;
+    const defaults = agents && typeof agents === 'object' ? agents.defaults : undefined;
+    const model = defaults && typeof defaults === 'object' ? defaults.model : undefined;
+    const primary = model && typeof model === 'object' ? str(model.primary) : '';
+    return primary.includes('/') ? primary.split('/', 1)[0] : '';
+}
+/**
+ * Scoped read of openclaw.json's top-level `models.providers.<id>` tables — `baseUrl`/`auth`
+ * (a strategy string, e.g. `"aws-sdk"`) only, never `apiKey`, `headers`, or the `models` catalog.
+ */
+function readModelProviders(raw) {
+    const models = raw?.models;
+    const providers = models && typeof models === 'object' ? models.providers : undefined;
+    const out = {};
+    if (providers && typeof providers === 'object') {
+        for (const [id, cfg] of Object.entries(providers)) {
+            if (!cfg || typeof cfg !== 'object')
+                continue;
+            const entry = cfg;
+            out[id] = { baseUrl: str(entry.baseUrl), auth: str(entry.auth) };
+        }
+    }
+    return out;
+}
+/**
+ * Aggregate OpenClaw session count / token usage / models / providers / version across every
+ * agent dir's sessions.json store. Returns a single-element array (one per-machine aggregate)
+ * or [] when there is no recent session data.
+ */
+function collectOpenclawTokenUsage(home = homedir()) {
+    const openclawDir = join(home, '.openclaw');
+    const stores = discoverSessionsStores(openclawDir);
+    if (stores.length === 0)
+        return [];
+    const cutoffMs = Date.now() - TOKEN_USAGE_RECENCY_DAYS * 24 * 60 * 60 * 1000;
+    const acc = {
+        sessionIds: new Set(),
+        models: new Set(),
+        providers: new Set(),
+        totals: emptyTotals(),
+        modelTokenSplit: {},
+    };
+    for (const store of stores) {
+        readSessionsStore(store, cutoffMs, acc);
+    }
+    if (acc.sessionIds.size === 0)
+        return [];
+    const openclawJson = parseOpenclawJson(openclawDir);
+    return [
+        {
+            file_type: TOKEN_USAGE_FILE_TYPE,
+            file_path: openclawDir,
+            raw_content: {
+                version: readVersion(openclawJson),
+                session_count: acc.sessionIds.size,
+                models: [...acc.models].sort(),
+                providers: [...acc.providers].sort(),
+                model_token_split: acc.modelTokenSplit,
+                window_days: TOKEN_USAGE_RECENCY_DAYS,
+                totals: acc.totals,
+                auth_modes_by_provider: readAuthModesByProvider(openclawJson),
+                primary_model_provider: readPrimaryModelProvider(openclawJson),
+                model_providers: readModelProviders(openclawJson),
+            },
+        },
+    ];
+}
+export { collectOpenclawTokenUsage, TOKEN_USAGE_RECENCY_DAYS, TOKEN_USAGE_FILE_TYPE };