fraim 2.0.103 → 2.0.105

package/dist/src/cli/commands/add-ide.js

@@ -45,6 +45,7 @@ const path_1 = __importDefault(require("path"));
 const ide_detector_1 = require("../setup/ide-detector");
 const mcp_config_generator_1 = require("../setup/mcp-config-generator");
 const codex_local_config_1 = require("../setup/codex-local-config");
+const claude_code_telemetry_1 = require("../setup/claude-code-telemetry");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
 const mcp_server_registry_1 = require("../mcp/mcp-server-registry");
 const get_provider_client_1 = require("../api/get-provider-client");
@@ -249,6 +250,10 @@ const configureIDEMCP = async (ide, fraimKey, tokens, providerConfigs) => {
         const status = localResult.created ? 'Created' : localResult.updated ? 'Updated' : 'Verified';
         console.log(chalk_1.default.green(`  ✅ ${status} local ${ide.name} config: ${localResult.path}`));
     }
+    // Enable token telemetry for Claude Code via project-level settings
+    if (ide.configType === 'claude-code') {
+        (0, claude_code_telemetry_1.ensureClaudeCodeTelemetryEnv)();
+    }
 };
 const listSupportedIDEs = () => {
     const allIDEs = (0, ide_detector_1.getAllSupportedIDEs)();

package/dist/src/cli/commands/add-provider.js

@@ -9,6 +9,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const prompts_1 = __importDefault(require("prompts"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const mcp_config_generator_1 = require("../setup/mcp-config-generator");
 const ide_detector_1 = require("../setup/ide-detector");
 const script_sync_utils_1 = require("../utils/script-sync-utils");
@@ -163,6 +164,28 @@ const runAddProvider = async (provider, options) => {
             }
         }
     }
+    // Check prerequisites for the provider's MCP server command
+    const providerDefCheck = await (0, provider_registry_1.getProvider)(provider);
+    if (providerDefCheck?.mcpServer?.type === 'stdio' && providerDefCheck.mcpServer.command && !process.env.FRAIM_SKIP_PREREQ_CHECK) {
+        const cmd = providerDefCheck.mcpServer.command;
+        // Only check non-standard commands (npx/node are assumed to be available)
+        if (!['npx', 'node', 'npm'].includes(cmd)) {
+            try {
+                (0, child_process_1.execSync)(`${cmd} --version`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+            }
+            catch {
+                const installInstructions = {
+                    uvx: 'Install uv first: https://docs.astral.sh/uv/getting-started/installation/\n' +
+                        '   macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh\n' +
+                        '   Windows:    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"',
+                };
+                console.log(chalk_1.default.red(`\n❌ "${cmd}" is required for ${providerName} but was not found on your system.\n`));
+                console.log(chalk_1.default.yellow(installInstructions[cmd] || `Please install "${cmd}" and try again.`));
+                console.log(chalk_1.default.gray('\nAfter installing, restart your terminal and run this command again.'));
+                process.exit(1);
+            }
+        }
+    }
     // Get credentials using generic prompt system
     try {
         // Build provided tokens/configs from CLI options

package/dist/src/cli/commands/init-project.js

@@ -16,6 +16,7 @@ const platform_detection_1 = require("../utils/platform-detection");
 const version_utils_1 = require("../utils/version-utils");
 const ide_detector_1 = require("../setup/ide-detector");
 const codex_local_config_1 = require("../setup/codex-local-config");
+const claude_code_telemetry_1 = require("../setup/claude-code-telemetry");
 const provider_registry_1 = require("../providers/provider-registry");
 const fraim_gitignore_1 = require("../utils/fraim-gitignore");
 const config_writer_1 = require("../../core/config-writer");
@@ -323,6 +324,11 @@ const runInitProject = async () => {
         const status = codexLocalResult.created ? 'Created' : codexLocalResult.updated ? 'Updated' : 'Verified';
         console.log(chalk_1.default.green(`${status} project Codex config at ${codexLocalResult.path}`));
     }
+    // Enable token telemetry for Claude Code (user-level, applies to all projects)
+    const claudeCodeAvailable = (0, ide_detector_1.detectInstalledIDEs)().some((ide) => ide.configType === 'claude-code');
+    if (claudeCodeAvailable) {
+        (0, claude_code_telemetry_1.ensureClaudeCodeTelemetryEnv)();
+    }
     const adapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot);
     if (adapterUpdates.length > 0) {
         console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${adapterUpdates.join(', ')}`));

package/dist/src/cli/setup/claude-code-telemetry.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Configures Claude Code user-level settings for FRAIM token telemetry.
+ *
+ * Writes OTel env vars to ~/.claude/settings.json so ALL Claude Code
+ * sessions push metrics to the FRAIM local proxy's OTLP receiver.
+ * User-level so it works across all projects without per-project setup.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureClaudeCodeTelemetryEnv = ensureClaudeCodeTelemetryEnv;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const chalk_1 = __importDefault(require("chalk"));
+const TELEMETRY_ENV = {
+    CLAUDE_CODE_ENABLE_TELEMETRY: '1',
+    OTEL_METRICS_EXPORTER: 'otlp',
+    OTEL_EXPORTER_OTLP_PROTOCOL: 'http/json',
+    OTEL_EXPORTER_OTLP_ENDPOINT: 'http://localhost:4318',
+};
+/**
+ * Ensure Claude Code user-level settings include OTel env vars for token telemetry.
+ * Writes to ~/.claude/settings.json. Merges without overwriting user-set values.
+ */
+function ensureClaudeCodeTelemetryEnv() {
+    const settingsDir = path_1.default.join(os_1.default.homedir(), '.claude');
+    const settingsPath = path_1.default.join(settingsDir, 'settings.json');
+    let settings = {};
+    if (fs_1.default.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs_1.default.readFileSync(settingsPath, 'utf8'));
+        }
+        catch {
+            // Corrupt file — will overwrite
+        }
+    }
+    else if (!fs_1.default.existsSync(settingsDir)) {
+        fs_1.default.mkdirSync(settingsDir, { recursive: true });
+    }
+    const existingEnv = settings.env || {};
+    let added = 0;
+    for (const [key, value] of Object.entries(TELEMETRY_ENV)) {
+        if (!(key in existingEnv)) {
+            existingEnv[key] = value;
+            added++;
+        }
+    }
+    if (added > 0) {
+        settings.env = existingEnv;
+        fs_1.default.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        console.log(chalk_1.default.green(`  ✅ Enabled token telemetry in ~/.claude/settings.json (${added} env vars)`));
+    }
+    else {
+        console.log(chalk_1.default.gray(`  ⏭️ Token telemetry already configured in ~/.claude/settings.json`));
+    }
+}

package/dist/src/local-mcp-server/otlp-metrics-receiver.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * Lightweight OTLP HTTP Metrics Receiver
+ *
+ * Accepts OTLP metric pushes from Claude Code when configured with:
+ *   OTEL_METRICS_EXPORTER=otlp
+ *   OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+ *   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+ *
+ * Multiple Claude Code sessions share one receiver on port 4318.
+ * Snapshots are stored per session ID and queryable via HTTP so any
+ * FRAIM proxy (not just the one that started the receiver) can fetch
+ * its own session's token data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOtlpMetrics = parseOtlpMetrics;
+exports.fetchSnapshot = fetchSnapshot;
+exports.startOtlpReceiver = startOtlpReceiver;
+exports.stopOtlpReceiver = stopOtlpReceiver;
+const http_1 = require("http");
+const DEFAULT_PORT = 4318;
+/** Stored token snapshots keyed by Claude Code session ID */
+const snapshots = new Map();
+/**
+ * Parse OTLP HTTP JSON metrics payload and extract token/cost data.
+ *
+ * OTLP JSON structure:
+ * { resourceMetrics: [{ scopeMetrics: [{ metrics: [{ name, sum: { dataPoints } }] }] }] }
+ */
+function parseOtlpMetrics(body) {
+    if (!body?.resourceMetrics)
+        return null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheCreationTokens = 0;
+    let costUsd = 0;
+    let claudeSessionId = null;
+    let model = null;
+    let foundTokenMetric = false;
+    for (const rm of body.resourceMetrics) {
+        for (const sm of rm.scopeMetrics || []) {
+            for (const metric of sm.metrics || []) {
+                const dataPoints = metric.sum?.dataPoints || metric.gauge?.dataPoints || [];
+                if (metric.name === 'claude_code.token.usage') {
+                    foundTokenMetric = true;
+                    for (const dp of dataPoints) {
+                        const attrs = parseAttributes(dp.attributes);
+                        const value = Number(dp.asInt ?? dp.asDouble ?? dp.value ?? 0);
+                        switch (attrs['type']) {
+                            case 'input':
+                                inputTokens += value;
+                                break;
+                            case 'output':
+                                outputTokens += value;
+                                break;
+                            case 'cacheRead':
+                                cacheReadTokens += value;
+                                break;
+                            case 'cacheCreation':
+                                cacheCreationTokens += value;
+                                break;
+                        }
+                        claudeSessionId = attrs['session.id'] || claudeSessionId;
+                        model = attrs['model'] || model;
+                    }
+                }
+                if (metric.name === 'claude_code.cost.usage') {
+                    for (const dp of dataPoints) {
+                        const value = Number(dp.asDouble ?? dp.asInt ?? dp.value ?? 0);
+                        costUsd += value;
+                        const attrs = parseAttributes(dp.attributes);
+                        claudeSessionId = attrs['session.id'] || claudeSessionId;
+                    }
+                }
+            }
+        }
+    }
+    if (!foundTokenMetric)
+        return null;
+    return {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheCreationTokens,
+        costUsd,
+        claudeSessionId,
+        model,
+        capturedAt: new Date(),
+    };
+}
+/**
+ * Parse OTLP attribute array into a key-value map.
+ * Attributes come as: [{ key: "name", value: { stringValue: "x" } }, ...]
+ */
+function parseAttributes(attrs) {
+    const result = {};
+    if (!Array.isArray(attrs))
+        return result;
+    for (const attr of attrs) {
+        if (attr.key && attr.value) {
+            result[attr.key] = attr.value.stringValue
+                ?? attr.value.intValue
+                ?? attr.value.doubleValue
+                ?? String(attr.value.value ?? '');
+        }
+    }
+    return result;
+}
+/**
+ * Parse URL query string into key-value pairs.
+ */
+function parseQuery(url) {
+    const idx = url.indexOf('?');
+    if (idx < 0)
+        return {};
+    const params = {};
+    for (const part of url.slice(idx + 1).split('&')) {
+        const [key, val] = part.split('=');
+        if (key)
+            params[decodeURIComponent(key)] = decodeURIComponent(val || '');
+    }
+    return params;
+}
+/**
+ * Handle incoming HTTP requests.
+ */
+function handleRequest(req, res) {
+    const url = req.url || '';
+    const pathname = url.split('?')[0];
+    // OTLP metrics push endpoint
+    if (req.method === 'POST' && pathname === '/v1/metrics') {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk; });
+        req.on('end', () => {
+            try {
+                const parsed = JSON.parse(body);
+                const snapshot = parseOtlpMetrics(parsed);
+                if (snapshot && snapshot.claudeSessionId) {
+                    snapshots.set(snapshot.claudeSessionId, snapshot);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end('{}');
+            }
+            catch {
+                res.writeHead(400);
+                res.end('{"error":"invalid json"}');
+            }
+        });
+        return;
+    }
+    // Query snapshot — used by any FRAIM proxy to fetch token data
+    // ?sessionId=X returns that session's snapshot
+    // ?latest=true returns the most recently updated snapshot
+    if (req.method === 'GET' && pathname === '/v1/snapshot') {
+        const query = parseQuery(url);
+        let snapshot;
+        if (query['sessionId']) {
+            snapshot = snapshots.get(query['sessionId']);
+        }
+        else {
+            // Return most recently captured snapshot across all sessions
+            let latest;
+            for (const s of snapshots.values()) {
+                if (!latest || s.capturedAt > latest.capturedAt) {
+                    latest = s;
+                }
+            }
+            snapshot = latest;
+        }
+        if (snapshot) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(snapshot));
+        }
+        else {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end('{"error":"no snapshot available"}');
+        }
+        return;
+    }
+    // Health check
+    if (req.method === 'GET' && pathname === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            status: 'ok',
+            sessionCount: snapshots.size,
+            sessions: [...snapshots.keys()],
+        }));
+        return;
+    }
+    res.writeHead(404);
+    res.end('');
+}
+/**
+ * Fetch a token snapshot from the OTLP receiver via HTTP.
+ * Works whether this process owns the receiver or another proxy does.
+ *
+ * @param sessionId If provided, fetches that specific session's snapshot.
+ *                  If omitted, fetches the most recently updated snapshot.
+ * @param log Optional logging function
+ */
+async function fetchSnapshot(sessionId, log) {
+    const port = parseInt(process.env.FRAIM_OTLP_PORT || String(DEFAULT_PORT), 10);
+    const query = sessionId ? `?sessionId=${encodeURIComponent(sessionId)}` : '';
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 2000);
+        const resp = await fetch(`http://127.0.0.1:${port}/v1/snapshot${query}`, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!resp.ok)
+            return null;
+        const data = await resp.json();
+        if (data.inputTokens !== undefined) {
+            return {
+                ...data,
+                capturedAt: new Date(data.capturedAt),
+            };
+        }
+        return null;
+    }
+    catch {
+        log?.('OTLP receiver not reachable — no token snapshot available');
+        return null;
+    }
+}
+/**
+ * Start the OTLP metrics receiver HTTP server.
+ * Only one receiver runs per machine — if port is in use, that's fine;
+ * this proxy will query the existing receiver via HTTP.
+ *
+ * @param log Optional logging function
+ * @returns Server info if started, null if port was in use (not an error)
+ */
+function startOtlpReceiver(log) {
+    const port = parseInt(process.env.FRAIM_OTLP_PORT || String(DEFAULT_PORT), 10);
+    try {
+        const server = (0, http_1.createServer)(handleRequest);
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                log?.(`OTLP receiver: port ${port} in use — will query existing receiver via HTTP`);
+            }
+            else {
+                log?.(`OTLP receiver error: ${err.message}`);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            log?.(`OTLP metrics receiver listening on http://127.0.0.1:${port}/v1/metrics`);
+        });
+        return { server, port };
+    }
+    catch (err) {
+        log?.(`Failed to start OTLP receiver: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Stop the OTLP receiver and clear stored snapshots.
+ */
+function stopOtlpReceiver(server) {
+    server.close();
+    snapshots.clear();
+}

package/dist/src/local-mcp-server/prometheus-scraper.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Prometheus Scraper for Claude Code OTel Token Usage Metrics
+ *
+ * Scrapes Claude Code's local Prometheus endpoint to capture cumulative
+ * token usage counters. Returns raw snapshot values — delta computation
+ * happens server-side per architecture constraint 15.2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePrometheusText = parsePrometheusText;
+exports.extractTokenSnapshot = extractTokenSnapshot;
+exports.scrapeTokenSnapshot = scrapeTokenSnapshot;
+/** Candidate Prometheus endpoint ports (OTel SDK defaults) */
+const CANDIDATE_PORTS = [9464, 8888];
+/** Candidate metric names for token usage (OTel dots→underscores, optional suffixes) */
+const TOKEN_METRIC_CANDIDATES = [
+    'claude_code_token_usage_total',
+    'claude_code_token_usage',
+    'claude_code_token_usage_tokens_total',
+    'claude_code_token_usage_tokens',
+];
+/** Candidate metric names for cost usage */
+const COST_METRIC_CANDIDATES = [
+    'claude_code_cost_usage_total',
+    'claude_code_cost_usage',
+    'claude_code_cost_usage_usd_total',
+    'claude_code_cost_usage_usd',
+];
+/**
+ * Parse Prometheus text exposition format into structured metrics.
+ *
+ * Format per line:  metric_name{label1="val1",label2="val2"} value [timestamp]
+ * Lines starting with # are comments (HELP, TYPE). Empty lines are skipped.
+ */
+function parsePrometheusText(text) {
+    const results = [];
+    for (const line of text.split('\n')) {
+        if (line.startsWith('#') || line.trim() === '')
+            continue;
+        // Match: metric_name{labels} value
+        const labeledMatch = line.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)\{([^}]*)\}\s+([\d.eE+-]+)/);
+        if (labeledMatch) {
+            const [, name, labelsStr, valueStr] = labeledMatch;
+            const labels = {};
+            for (const pair of labelsStr.matchAll(/(\w+)="([^"]*)"/g)) {
+                labels[pair[1]] = pair[2];
+            }
+            results.push({ name, labels, value: parseFloat(valueStr) });
+            continue;
+        }
+        // Match: metric_name value (no labels)
+        const noLabelMatch = line.match(/^([a-zA-Z_:][a-zA-Z0-9_:]*)\s+([\d.eE+-]+)/);
+        if (noLabelMatch) {
+            const [, name, valueStr] = noLabelMatch;
+            results.push({ name, labels: {}, value: parseFloat(valueStr) });
+        }
+    }
+    return results;
+}
+/**
+ * Extract a TokenSnapshot from parsed Prometheus metrics.
+ * Tries multiple candidate metric names for resilience to SDK version changes.
+ */
+function extractTokenSnapshot(metrics) {
+    const snapshot = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        costUsd: 0,
+        claudeSessionId: null,
+        model: null,
+        capturedAt: new Date(),
+    };
+    for (const m of metrics) {
+        if (TOKEN_METRIC_CANDIDATES.includes(m.name)) {
+            const type = m.labels['type'];
+            switch (type) {
+                case 'input':
+                    snapshot.inputTokens = m.value;
+                    break;
+                case 'output':
+                    snapshot.outputTokens = m.value;
+                    break;
+                case 'cacheRead':
+                    snapshot.cacheReadTokens = m.value;
+                    break;
+                case 'cacheCreation':
+                    snapshot.cacheCreationTokens = m.value;
+                    break;
+            }
+            snapshot.claudeSessionId = m.labels['session_id'] || snapshot.claudeSessionId;
+            snapshot.model = m.labels['model'] || snapshot.model;
+        }
+        if (COST_METRIC_CANDIDATES.includes(m.name)) {
+            snapshot.costUsd += m.value;
+            snapshot.claudeSessionId = m.labels['session_id'] || snapshot.claudeSessionId;
+        }
+    }
+    return snapshot;
+}
+/**
+ * Attempt to fetch Prometheus metrics from a candidate endpoint.
+ * Returns response text or null on failure.
+ */
+async function tryFetch(port, timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const resp = await fetch(`http://localhost:${port}/metrics`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (resp.ok) {
+            return await resp.text();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scrape Claude Code's Prometheus endpoint and return a TokenSnapshot.
+ *
+ * Returns null if:
+ * - Prometheus endpoint is not available (OTel not enabled)
+ * - Scrape times out (>2s by default)
+ * - No matching token metrics found
+ *
+ * @param log Optional logging function for debug output
+ */
+async function scrapeTokenSnapshot(log) {
+    const configuredPort = process.env.FRAIM_PROMETHEUS_PORT;
+    const ports = configuredPort ? [parseInt(configuredPort, 10)] : CANDIDATE_PORTS;
+    const timeoutMs = 2000;
+    for (const port of ports) {
+        const text = await tryFetch(port, timeoutMs);
+        if (text && text.includes('#')) {
+            const metrics = parsePrometheusText(text);
+            const snapshot = extractTokenSnapshot(metrics);
+            // Only return if we actually found token metrics
+            if (snapshot.inputTokens > 0 || snapshot.outputTokens > 0) {
+                log?.(`Captured token snapshot from localhost:${port} (input=${snapshot.inputTokens}, output=${snapshot.outputTokens})`);
+                return snapshot;
+            }
+            log?.(`Prometheus endpoint found at localhost:${port} but no token metrics matched`);
+        }
+    }
+    log?.('No Prometheus endpoint available — token snapshot skipped');
+    return null;
+}

package/dist/src/local-mcp-server/stdio-server.js

@@ -31,6 +31,7 @@ const local_registry_resolver_1 = require("../core/utils/local-registry-resolver
 const ai_mentor_1 = require("../core/ai-mentor");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const usage_collector_js_1 = require("./usage-collector.js");
+const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
 const learning_context_builder_js_1 = require("./learning-context-builder.js");
 /**
  * Handle template substitution logic separately for better testability
@@ -398,6 +399,7 @@ class FraimLocalMCPServer {
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
+        this.otlpServer = null;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -415,6 +417,8 @@ class FraimLocalMCPServer {
         // Initialize usage collector
         this.usageCollector = new usage_collector_js_1.UsageCollector();
         this.log('📊 Usage analytics collector initialized');
+        // Start OTLP metrics receiver for Claude Code token telemetry
+        this.otlpServer = (0, otlp_metrics_receiver_js_1.startOtlpReceiver)((msg) => this.log(`📊 ${msg}`));
     }
     /**
      * Load API key from environment variable or user config file
@@ -1824,6 +1828,9 @@ class FraimLocalMCPServer {
         const cleanup = () => {
             clearInterval(uploadInterval);
             this.usageCollector.shutdown();
+            if (this.otlpServer?.server) {
+                (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
+            }
         };
         process.stdin.on('data', async (chunk) => {
             buffer += chunk;
@@ -1843,7 +1850,7 @@ class FraimLocalMCPServer {
                             // Only send response if we got one (null means we handled it internally)
                             if (response) {
                                 // Collect usage for all tools/call requests before sending response
-                                this.collectUsageForResponse(message, response);
+                                await this.collectUsageForResponse(message, response);
                                 process.stdout.write(JSON.stringify(response) + '\n');
                             }
                         }
@@ -1900,7 +1907,7 @@ class FraimLocalMCPServer {
     /**
      * Collect usage analytics for tools/call requests
      */
-    collectUsageForResponse(request, response) {
+    async collectUsageForResponse(request, response) {
         // Only collect usage for tools/call requests
         if (request.method !== 'tools/call') {
             return;
@@ -1919,6 +1926,19 @@ class FraimLocalMCPServer {
                 const afterCount = this.usageCollector.getEventCount();
                 if (afterCount > beforeCount) {
                     this.log(`📊 ✅ Event queued successfully (queue: ${afterCount})`);
+                    // Fetch token snapshot from OTLP receiver for seekMentoring calls
+                    if (toolName === 'seekMentoring') {
+                        try {
+                            const snapshot = await (0, otlp_metrics_receiver_js_1.fetchSnapshot)(undefined, (msg) => this.log(`📊 ${msg}`));
+                            if (snapshot) {
+                                this.usageCollector.attachTokenSnapshot(snapshot);
+                                this.log(`📊 🔢 Token snapshot attached (input=${snapshot.inputTokens}, output=${snapshot.outputTokens}, session=${snapshot.claudeSessionId})`);
+                            }
+                        }
+                        catch (err) {
+                            this.log(`📊 ⚠️ Token snapshot fetch failed (non-blocking): ${err.message}`);
+                        }
+                    }
                 }
                 else {
                     this.log(`📊 ⚠️ Event not queued - tool may not be tracked: ${toolName}`);

package/dist/src/local-mcp-server/usage-collector.js

@@ -148,7 +148,7 @@ class UsageCollector {
             case 'seekMentoring':
                 return { type: 'mentoring', name: UsageCollector.resolveMentoringJobName(args), category: 'mentoring' };
             case 'list_fraim_jobs':
-                return { type: 'job', name: 'list', category: 'none' };
+                return null; // Not a job execution — skip tracking
             case 'fraim_connect':
                 return { type: 'session', name: 'connect' };
             default:
@@ -163,6 +163,15 @@ class UsageCollector {
         this.events = [];
         return eventsToUpload;
     }
+    /**
+     * Attach a token snapshot to the most recently queued event.
+     * Used to associate Prometheus-scraped token data with seekMentoring events.
+     */
+    attachTokenSnapshot(snapshot) {
+        if (this.events.length > 0) {
+            this.events[this.events.length - 1].tokenSnapshot = snapshot;
+        }
+    }
     /**
      * Get current event count
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.103",
+  "version": "2.0.105",
   "description": "FRAIM CLI - Framework for Rigor-based AI Management (alias for fraim-framework)",
   "main": "index.js",
   "bin": {
@@ -53,7 +53,8 @@
     "validate:provider-action-mappings": "tsx scripts/validate-provider-action-mappings.ts",
     "validate:fidelity": "tsx scripts/validate-fidelity.ts",
     "validate:config-tokens": "tsx scripts/validate-config-tokens.ts",
-    "validate:template-syntax": "tsx scripts/validate-template-syntax.ts"
+    "validate:template-syntax": "tsx scripts/validate-template-syntax.ts",
+    "validate:backup": "bash scripts/backup/validate-pitr-restore.sh"
   },
   "repository": {
     "type": "git",