@cleocode/core 2026.3.59 → 2026.3.61

package/dist/metrics/otel-integration.js

@@ -0,0 +1,263 @@
+/**
+ * OpenTelemetry integration for Claude Code metrics.
+ *
+ * Captures real token usage data from Claude Code OTel exports.
+ * Supports setup, parsing, aggregation, and session comparison.
+ *
+ * @task T4454
+ * @epic T4454
+ */
+import { appendFileSync, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getCleoDir } from '../paths.js';
+import { isoTimestamp } from './common.js';
+function getOtelDir(cwd) {
+    return process.env.OTEL_METRICS_DIR ?? join(getCleoDir(cwd), 'metrics', 'otel');
+}
+function getTokenMetricsPath(cwd) {
+    return join(getOtelDir(cwd), 'token_metrics.jsonl');
+}
+/** Check if OTel telemetry is enabled. */
+export function isOtelEnabled() {
+    return process.env.CLAUDE_CODE_ENABLE_TELEMETRY === '1';
+}
+/** Get environment variable commands for OTel capture setup. */
+export function getOtelSetupCommands(mode = 'file', cwd) {
+    switch (mode) {
+        case 'console':
+            return [
+                'export CLAUDE_CODE_ENABLE_TELEMETRY=1',
+                'export OTEL_METRICS_EXPORTER=console',
+                'export OTEL_METRIC_EXPORT_INTERVAL=5000',
+            ].join('\n');
+        case 'file':
+            return [
+                'export CLAUDE_CODE_ENABLE_TELEMETRY=1',
+                'export OTEL_METRICS_EXPORTER=otlp',
+                'export OTEL_EXPORTER_OTLP_PROTOCOL=http/json',
+                `export OTEL_EXPORTER_OTLP_ENDPOINT=file://${getOtelDir(cwd)}/`,
+            ].join('\n');
+        case 'prometheus':
+            return [
+                'export CLAUDE_CODE_ENABLE_TELEMETRY=1',
+                'export OTEL_METRICS_EXPORTER=prometheus',
+                '# Metrics available at localhost:9464/metrics',
+            ].join('\n');
+    }
+}
+/** Find the most recent OTel metrics JSON file. */
+function findLatestMetricsFile(cwd) {
+    const otelDir = getOtelDir(cwd);
+    if (!existsSync(otelDir))
+        return null;
+    const files = readdirSync(otelDir)
+        .filter((f) => f.endsWith('.json'))
+        .map((f) => join(otelDir, f))
+        .filter((f) => {
+        try {
+            return statSync(f).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    return files[0] ?? null;
+}
+/** Parse OTel token metrics from collected data. */
+export function parseTokenMetrics(inputFile, cwd) {
+    const file = inputFile ?? findLatestMetricsFile(cwd);
+    if (!file || !existsSync(file))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf-8'));
+        // Standard OTel JSON format
+        if (raw.resourceMetrics) {
+            const points = [];
+            for (const rm of raw.resourceMetrics ?? []) {
+                for (const sm of rm.scopeMetrics ?? []) {
+                    for (const metric of sm.metrics ?? []) {
+                        if (metric.name !== 'claude_code.token.usage')
+                            continue;
+                        for (const dp of metric.sum?.dataPoints ?? []) {
+                            const attrs = dp.attributes ?? [];
+                            const typeAttr = attrs.find((a) => a.key === 'type');
+                            const modelAttr = attrs.find((a) => a.key === 'model');
+                            points.push({
+                                timestamp: dp.timeUnixNano,
+                                type: typeAttr?.value?.stringValue ?? 'unknown',
+                                model: modelAttr?.value?.stringValue ?? 'unknown',
+                                tokens: dp.asInt ?? Math.floor(dp.asDouble ?? 0),
+                            });
+                        }
+                    }
+                }
+            }
+            return points;
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Get aggregated token counts from OTel data. */
+export function getSessionTokens(sessionId, cwd) {
+    let input = 0;
+    let output = 0;
+    let cacheRead = 0;
+    let cacheCreate = 0;
+    for (const point of parseTokenMetrics(undefined, cwd)) {
+        switch (point.type) {
+            case 'input':
+                input += point.tokens;
+                break;
+            case 'output':
+                output += point.tokens;
+                break;
+            case 'cacheRead':
+                cacheRead += point.tokens;
+                break;
+            case 'cacheCreation':
+                cacheCreate += point.tokens;
+                break;
+        }
+    }
+    return {
+        session_id: sessionId ?? null,
+        tokens: {
+            input,
+            output,
+            cache_read: cacheRead,
+            cache_creation: cacheCreate,
+            total: input + output,
+            effective: input + output - cacheRead,
+        },
+        api_requests: 0,
+        source: 'otel',
+    };
+}
+/** Record token counts at session start. */
+export async function recordSessionStart(sessionId, cwd) {
+    const otelDir = getOtelDir(cwd);
+    await mkdir(otelDir, { recursive: true });
+    const snapshot = getSessionTokens(sessionId, cwd);
+    const entry = {
+        ...snapshot,
+        timestamp: isoTimestamp(),
+        event: 'session_start',
+    };
+    const metricsPath = getTokenMetricsPath(cwd);
+    appendFileSync(metricsPath, JSON.stringify(entry) + '\n');
+    return entry;
+}
+/** Record token counts at session end. */
+export async function recordSessionEnd(sessionId, cwd) {
+    const otelDir = getOtelDir(cwd);
+    await mkdir(otelDir, { recursive: true });
+    const current = getSessionTokens(sessionId, cwd);
+    const metricsPath = getTokenMetricsPath(cwd);
+    // Find session start
+    let deltaInput = 0;
+    let deltaOutput = 0;
+    if (existsSync(metricsPath)) {
+        const lines = readFileSync(metricsPath, 'utf-8').trim().split('\n').filter(Boolean);
+        const startLine = lines
+            .reverse()
+            .find((l) => l.includes(`"session_id":"${sessionId}"`) && l.includes('session_start'));
+        if (startLine) {
+            const startData = JSON.parse(startLine);
+            deltaInput = current.tokens.input - startData.tokens.input;
+            deltaOutput = current.tokens.output - startData.tokens.output;
+        }
+    }
+    const summary = {
+        session_id: sessionId,
+        timestamp: isoTimestamp(),
+        event: 'session_end',
+        session_tokens: {
+            input: deltaInput,
+            output: deltaOutput,
+            total: deltaInput + deltaOutput,
+        },
+        cumulative: current.tokens,
+    };
+    appendFileSync(metricsPath, JSON.stringify(summary) + '\n');
+    return summary;
+}
+/** Compare token usage between two sessions. */
+export function compareSessions(sessionA, sessionB, cwd) {
+    const metricsPath = getTokenMetricsPath(cwd);
+    if (!existsSync(metricsPath)) {
+        return { error: 'One or both sessions not found' };
+    }
+    const lines = readFileSync(metricsPath, 'utf-8').trim().split('\n').filter(Boolean);
+    const findSessionEnd = (id) => {
+        const line = lines
+            .reverse()
+            .find((l) => l.includes(`"session_id":"${id}"`) && l.includes('session_end'));
+        if (!line)
+            return 0;
+        const data = JSON.parse(line);
+        return data.session_tokens?.total ?? 0;
+    };
+    const aTotal = findSessionEnd(sessionA);
+    const bTotal = findSessionEnd(sessionB);
+    if (aTotal === 0 && bTotal === 0) {
+        return { error: 'One or both sessions not found' };
+    }
+    const difference = bTotal - aTotal;
+    const savingsPercent = bTotal > 0 ? Math.floor((difference * 100) / bTotal) : 0;
+    let verdict;
+    if (savingsPercent >= 50)
+        verdict = 'Significant savings';
+    else if (savingsPercent >= 20)
+        verdict = 'Moderate savings';
+    else if (savingsPercent >= 0)
+        verdict = 'Minimal difference';
+    else
+        verdict = 'Session A used more tokens';
+    return {
+        comparison: {
+            session_a: { id: sessionA, total_tokens: aTotal },
+            session_b: { id: sessionB, total_tokens: bTotal },
+        },
+        difference,
+        savings_percent: savingsPercent,
+        winner: aTotal < bTotal ? sessionA : sessionB,
+        verdict,
+    };
+}
+/** Get statistics about token usage across sessions. */
+export function getTokenStats(cwd) {
+    const metricsPath = getTokenMetricsPath(cwd);
+    if (!existsSync(metricsPath)) {
+        return { error: 'No token metrics recorded' };
+    }
+    const lines = readFileSync(metricsPath, 'utf-8').trim().split('\n').filter(Boolean);
+    const endEvents = lines.filter((l) => l.includes('session_end'));
+    if (endEvents.length === 0) {
+        return { sessions: 0, avg_tokens: 0, min_tokens: 0, max_tokens: 0 };
+    }
+    let sum = 0;
+    let min = Infinity;
+    let max = 0;
+    for (const line of endEvents) {
+        const data = JSON.parse(line);
+        const tokens = data.session_tokens?.total ?? 0;
+        sum += tokens;
+        if (tokens < min)
+            min = tokens;
+        if (tokens > max)
+            max = tokens;
+    }
+    return {
+        sessions_tracked: endEvents.length,
+        total_tokens_all_sessions: sum,
+        avg_tokens_per_session: Math.floor(sum / endEvents.length),
+        min_tokens_session: min === Infinity ? 0 : min,
+        max_tokens_session: max,
+    };
+}
+//# sourceMappingURL=otel-integration.js.map

package/dist/metrics/otel-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-integration.js","sourceRoot":"","sources":["../../src/metrics/otel-integration.ts"],"names":[],"mappings":"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"}

package/dist/metrics/provider-detection.js

@@ -0,0 +1,103 @@
+import { basename } from 'node:path';
+import { detectProjectProviders, getProvider, resolveAlias, } from '@cleocode/caamp';
+function inferProviderFromVendor(vendor) {
+    const value = (vendor ?? '').trim().toLowerCase();
+    if (!value)
+        return undefined;
+    if (value.includes('anthropic') || value.includes('claude'))
+        return 'anthropic';
+    if (value.includes('openai') || value.includes('codex') || value.includes('chatgpt'))
+        return 'openai';
+    if (value.includes('google') || value.includes('gemini'))
+        return 'google';
+    if (value.includes('xai') || value.includes('grok'))
+        return 'xai';
+    return undefined;
+}
+function getRuntimeHints(snapshot) {
+    const argv = snapshot.argv ?? process.argv;
+    const env = snapshot.env ?? process.env;
+    const hints = new Set();
+    const bin = basename(argv[1] ?? argv[0] ?? '').replace(/\.[^.]+$/, '');
+    if (bin)
+        hints.add(bin);
+    if (env['CLAUDE_CODE_ENABLE_TELEMETRY'] || env['CLAUDE_CODE_ENTRYPOINT']) {
+        hints.add('claude-code');
+        hints.add('claude');
+    }
+    if (env['OPENCODE_AGENT'] || env['OPENCODE']) {
+        hints.add('opencode');
+    }
+    if (env['CURSOR_TRACE_ID'] || env['CURSOR_AGENT']) {
+        hints.add('cursor');
+    }
+    return Array.from(hints);
+}
+function pickDetectionByHint(detections, hints) {
+    for (const hint of hints) {
+        const resolved = resolveAlias(hint);
+        const direct = detections.find((entry) => entry.provider.id === resolved || entry.provider.id === hint);
+        if (direct)
+            return direct;
+        const byAlias = detections.find((entry) => entry.provider.aliases.includes(hint) ||
+            entry.provider.agentFlag === hint ||
+            entry.provider.toolName.toLowerCase() === hint.toLowerCase());
+        if (byAlias)
+            return byAlias;
+        const provider = getProvider(resolved);
+        if (provider) {
+            return {
+                provider,
+                installed: true,
+                methods: [],
+                projectDetected: false,
+            };
+        }
+    }
+    return null;
+}
+export function selectRuntimeProviderContext(detections, snapshot = {}) {
+    const hints = getRuntimeHints(snapshot);
+    const hinted = pickDetectionByHint(detections, hints);
+    const projectMatches = detections.filter((entry) => entry.projectDetected);
+    const installed = detections.filter((entry) => entry.installed);
+    const selected = hinted ??
+        (projectMatches.length === 1 ? projectMatches[0] : null) ??
+        (installed.length === 1 ? installed[0] : null);
+    if (!selected) {
+        return {
+            runtimeCandidates: installed.map((entry) => entry.provider.id),
+        };
+    }
+    return {
+        runtimeProviderId: selected.provider.id,
+        runtimeToolName: selected.provider.toolName,
+        runtimeVendor: selected.provider.vendor,
+        runtimeInstructionFile: selected.provider.instructFile,
+        runtimeProjectDetected: selected.projectDetected,
+        runtimeDetectionMethods: selected.methods,
+        runtimeCandidates: installed.map((entry) => entry.provider.id),
+        inferredModelProvider: inferProviderFromVendor(selected.provider.vendor),
+    };
+}
+let cachedRuntimeProvider = null;
+export function detectRuntimeProviderContext(snapshot = {}) {
+    if (!snapshot.cwd && !snapshot.argv && !snapshot.env && cachedRuntimeProvider) {
+        return cachedRuntimeProvider;
+    }
+    try {
+        const detections = detectProjectProviders(snapshot.cwd ?? process.cwd());
+        const context = selectRuntimeProviderContext(detections, snapshot);
+        if (!snapshot.cwd && !snapshot.argv && !snapshot.env) {
+            cachedRuntimeProvider = context;
+        }
+        return context;
+    }
+    catch {
+        return {};
+    }
+}
+export function resetRuntimeProviderContextCache() {
+    cachedRuntimeProvider = null;
+}
+//# sourceMappingURL=provider-detection.js.map

package/dist/metrics/provider-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-detection.js","sourceRoot":"","sources":["../../src/metrics/provider-detection.ts"],"names":[],"mappings":"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"}

package/dist/metrics/token-estimation.js

@@ -0,0 +1,253 @@
+/**
+ * Token usage estimation and tracking.
+ *
+ * Estimates token consumption using heuristics (1 token ~ 4 chars).
+ * Logs events to TOKEN_USAGE.jsonl for value-proof metrics.
+ *
+ * @task T4454
+ * @epic T4454
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getCleoDir } from '../paths.js';
+import { isoTimestamp } from './common.js';
+let currentSession = null;
+function getTokenFilePath(cwd) {
+    return join(getCleoDir(cwd), 'metrics', 'TOKEN_USAGE.jsonl');
+}
+function isTrackingEnabled() {
+    return (process.env.CLEO_TRACK_TOKENS ?? '1') === '1';
+}
+/** Estimate token count from text. ~4 characters per token. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Estimate token count from a file. */
+export function estimateTokensFromFile(filePath) {
+    if (!existsSync(filePath))
+        return 0;
+    const size = statSync(filePath).size;
+    return Math.ceil(size / 4);
+}
+/** Log a token usage event to the JSONL file. */
+export async function logTokenEvent(eventType, tokens, source, taskId, context, cwd) {
+    if (!isTrackingEnabled())
+        return;
+    const tokenFile = getTokenFilePath(cwd);
+    await mkdir(dirname(tokenFile), { recursive: true });
+    const entry = {
+        timestamp: isoTimestamp(),
+        event_type: eventType,
+        estimated_tokens: tokens,
+        source,
+        task_id: taskId ?? null,
+        session_id: currentSession?.sessionId ?? null,
+        context: context ?? {},
+    };
+    try {
+        await appendFile(tokenFile, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // Token tracking failures are non-fatal
+    }
+    // Update session totals
+    if (currentSession) {
+        const current = currentSession.tokensByType[eventType] ?? 0;
+        currentSession.tokensByType[eventType] = current + tokens;
+    }
+}
+/** Track a file read with token estimate. */
+export async function trackFileRead(filePath, purpose, taskId, cwd) {
+    if (!isTrackingEnabled())
+        return 0;
+    const tokens = estimateTokensFromFile(filePath);
+    const eventTypeMap = {
+        manifest: 'manifest_read',
+        full_file: 'full_file_read',
+        full: 'full_file_read',
+        skill: 'skill_inject',
+        protocol: 'protocol_inject',
+    };
+    const eventType = eventTypeMap[purpose] ?? 'file_read';
+    await logTokenEvent(eventType, tokens, filePath, taskId, undefined, cwd);
+    return tokens;
+}
+/** Track a manifest query (partial read). */
+export async function trackManifestQuery(queryType, resultCount, taskId, cwd) {
+    if (!isTrackingEnabled())
+        return 0;
+    // Each manifest entry is ~200 tokens
+    const tokens = resultCount * 200;
+    await logTokenEvent('manifest_query', tokens, `MANIFEST.jsonl:${queryType}`, taskId, { query_type: queryType, result_count: resultCount }, cwd);
+    return tokens;
+}
+/** Track skill injection with tokens. */
+export async function trackSkillInjection(skillName, tier, tokens, taskId, cwd) {
+    if (!isTrackingEnabled())
+        return;
+    await logTokenEvent('skill_inject', tokens, `skills/${skillName}`, taskId, { skill: skillName, tier }, cwd);
+}
+/** Track final prompt size. */
+export async function trackPromptBuild(prompt, taskId, skillsUsed, cwd) {
+    if (!isTrackingEnabled())
+        return 0;
+    const tokens = estimateTokens(prompt);
+    await logTokenEvent('prompt_build', tokens, 'spawn_prompt', taskId, { skills: skillsUsed }, cwd);
+    return tokens;
+}
+/** Track subagent output tokens. */
+export async function trackSpawnOutput(taskId, outputText, sessionId, cwd) {
+    if (!isTrackingEnabled())
+        return 0;
+    const tokens = estimateTokens(outputText);
+    await logTokenEvent('spawn_output', tokens, 'subagent_response', taskId, { session_id: sessionId ?? '' }, cwd);
+    return tokens;
+}
+/** Track complete spawn cycle (prompt + output). */
+export async function trackSpawnComplete(taskId, promptTokens, outputTokens, sessionId, cwd) {
+    if (!isTrackingEnabled())
+        return 0;
+    const totalTokens = promptTokens + outputTokens;
+    const baselineTokens = totalTokens * 10;
+    const savedTokens = baselineTokens - totalTokens;
+    const savingsPercent = baselineTokens > 0 ? Math.floor((savedTokens * 100) / baselineTokens) : 0;
+    await logTokenEvent('spawn_complete', totalTokens, 'spawn_cycle', taskId, {
+        prompt_tokens: promptTokens,
+        output_tokens: outputTokens,
+        total_tokens: totalTokens,
+        baseline_tokens: baselineTokens,
+        saved_tokens: savedTokens,
+        savings_percent: savingsPercent,
+        session_id: sessionId ?? '',
+    }, cwd);
+    return totalTokens;
+}
+/** Start tracking tokens for a session. */
+export async function startTokenSession(sessionId, cwd) {
+    currentSession = {
+        sessionId,
+        startTime: isoTimestamp(),
+        tokensByType: {},
+    };
+    await logTokenEvent('session_start', 0, 'session', undefined, { session_id: sessionId }, cwd);
+}
+/** End token tracking session with summary. */
+export async function endTokenSession(cwd) {
+    if (!currentSession)
+        return null;
+    const manifestTokens = currentSession.tokensByType['manifest_read'] ?? 0;
+    const fullFileTokens = currentSession.tokensByType['full_file_read'] ?? 0;
+    const skillTokens = currentSession.tokensByType['skill_inject'] ?? 0;
+    const promptTokens = currentSession.tokensByType['prompt_build'] ?? 0;
+    const total = manifestTokens + fullFileTokens + skillTokens + promptTokens;
+    const avoidedTokens = manifestTokens * 9;
+    const savingsPercent = total > 0 ? Math.floor((avoidedTokens * 100) / (total + avoidedTokens)) : 0;
+    const summary = {
+        session_id: currentSession.sessionId,
+        start: currentSession.startTime,
+        end: isoTimestamp(),
+        tokens: {
+            manifest_reads: manifestTokens,
+            full_file_reads: fullFileTokens,
+            skill_injections: skillTokens,
+            prompt_builds: promptTokens,
+            total,
+        },
+        savings: {
+            avoided_tokens: avoidedTokens,
+            savings_percent: savingsPercent,
+        },
+    };
+    await logTokenEvent('session_end', total, 'session', undefined, { ...summary }, cwd);
+    currentSession = null;
+    return summary;
+}
+/** Get token usage summary for a time period. */
+export function getTokenSummary(days = 7, cwd) {
+    const tokenFile = getTokenFilePath(cwd);
+    if (!existsSync(tokenFile)) {
+        return { error: 'No token data', manifest_tokens: 0, full_file_tokens: 0, savings_percent: 0 };
+    }
+    const threshold = new Date();
+    threshold.setDate(threshold.getDate() - days);
+    const thresholdStr = threshold.toISOString();
+    const entries = readFileSync(tokenFile, 'utf-8').trim().split('\n').filter(Boolean);
+    let manifestTokens = 0;
+    let fullFileTokens = 0;
+    let skillTokens = 0;
+    let promptTokensSum = 0;
+    for (const line of entries) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.timestamp < thresholdStr)
+                continue;
+            switch (entry.event_type) {
+                case 'manifest_read':
+                case 'manifest_query':
+                    manifestTokens += entry.estimated_tokens;
+                    break;
+                case 'full_file_read':
+                    fullFileTokens += entry.estimated_tokens;
+                    break;
+                case 'skill_inject':
+                    skillTokens += entry.estimated_tokens;
+                    break;
+                case 'prompt_build':
+                    promptTokensSum += entry.estimated_tokens;
+                    break;
+            }
+        }
+        catch {
+            // Skip malformed entries
+        }
+    }
+    const total = manifestTokens + fullFileTokens + skillTokens + promptTokensSum;
+    const avoided = manifestTokens * 9;
+    const savings = total > 0 ? Math.floor((avoided * 100) / (total + avoided)) : 0;
+    return {
+        period_days: days,
+        tokens: {
+            manifest_reads: manifestTokens,
+            full_file_reads: fullFileTokens,
+            skill_injections: skillTokens,
+            prompt_builds: promptTokensSum,
+            total,
+        },
+        savings: {
+            avoided_tokens: avoided,
+            savings_percent: savings,
+            message: `Using manifest saves ~${savings}% context compared to full files`,
+        },
+    };
+}
+/** Compare manifest vs full file token usage strategies. */
+export function compareManifestVsFull(manifestEntries) {
+    const manifestTokens = manifestEntries * 200;
+    const fullFileTokens = manifestEntries * 2000;
+    const savings = fullFileTokens - manifestTokens;
+    const savingsPercent = fullFileTokens > 0 ? Math.floor((savings * 100) / fullFileTokens) : 0;
+    let verdict;
+    if (savingsPercent >= 80)
+        verdict = 'Excellent';
+    else if (savingsPercent >= 50)
+        verdict = 'Good';
+    else
+        verdict = 'Moderate';
+    return {
+        manifest_entries_read: manifestEntries,
+        manifest_tokens: manifestTokens,
+        full_file_equivalent: fullFileTokens,
+        tokens_saved: savings,
+        savings_percent: savingsPercent,
+        verdict,
+    };
+}
+/** Get tracking status. */
+export function getTrackingStatus() {
+    return {
+        tracking_enabled: isTrackingEnabled(),
+        env_var: process.env.CLEO_TRACK_TOKENS ?? '1',
+    };
+}
+//# sourceMappingURL=token-estimation.js.map

package/dist/metrics/token-estimation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimation.js","sourceRoot":"","sources":["../../src/metrics/token-estimation.ts"],"names":[],"mappings":"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"}