@nekzus/liop 1.2.0-alpha.10

package/dist/crypto/verifier.js

@@ -0,0 +1,96 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Piscina } from "piscina";
+import { log } from "../utils/logger.js";
+import { deriveLogicImageDigest } from "./logic-image-id.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * LIOP Tier-0 Industrial Verifier
+ *
+ * This engine is responsible for the trustless verification of remote logic execution.
+ * It validates both the integrity of the code (ZkImageID) and the mathematical proof
+ * of its execution (ZkSeal), as well as hardware-level attestation (TEE).
+ */
+export class LiopVerifier {
+    // Singleton Worker Pool for heavy ZK verification
+    static zkWorkerPool = null;
+    getZkPool() {
+        if (!LiopVerifier.zkWorkerPool) {
+            const isTS = import.meta.url.endsWith(".ts");
+            const workerExt = isTS ? ".ts" : ".js";
+            let execArgv = [];
+            if (isTS) {
+                try {
+                    const req = createRequire(import.meta.url);
+                    const tsxPkg = req.resolve("tsx/package.json");
+                    const absoluteTsx = pathToFileURL(path.join(path.dirname(tsxPkg), "dist", "loader.mjs")).href;
+                    execArgv = ["--import", absoluteTsx];
+                }
+                catch (_e) {
+                    execArgv = ["--import", "tsx"];
+                }
+            }
+            LiopVerifier.zkWorkerPool = new Piscina({
+                filename: path.resolve(__dirname, `../workers/zk-verifier${workerExt}`),
+                minThreads: 1,
+                maxThreads: 2, // Minimal footprint since verification is fast compared to generation
+                idleTimeout: 30000,
+                execArgv,
+            });
+        }
+        return LiopVerifier.zkWorkerPool;
+    }
+    /**
+     * Verifies a Zero-Knowledge Receipt from a remote LIOP node via Worker Pool.
+     *
+     * @param logicPayload The raw WASM or JS logic that was sent to the provider.
+     * @param remoteImageIdHex The ImageID reported by the provider (must match our local calculation).
+     * @param zkReceipt The mathematical proof (Seal + Journal) from the zkVM.
+     */
+    async verifyZkReceipt(logicPayload, remoteImageIdHex, zkReceipt) {
+        const pool = this.getZkPool();
+        if (!pool)
+            throw new Error("Worker pool initialization failed");
+        const result = await pool.run({
+            action: "verify_receipt",
+            logicPayload: new Uint8Array(logicPayload),
+            remoteImageIdHex,
+            zkReceipt: new Uint8Array(zkReceipt),
+        });
+        if (result.verified) {
+            log.info(`[LiopVerifier] ${result.message}`);
+            return true;
+        }
+        log.error(`[LiopVerifier] FAILED: ${result.message}`);
+        return false;
+    }
+    /**
+     * Verifies if a node is running inside an authenticated TEE (e.g. AWS Nitro).
+     *
+     * @param attestationReport The COSE-signed attestation document from the hardware.
+     */
+    async verifyTeeAttestation(attestationReport) {
+        if (attestationReport.length === 0)
+            return true; // Optional in Mesh Alpha
+        try {
+            // Architecture for AWS Nitro Enclaves:
+            // 1. Decode CBOR/COSE
+            // 2. Verify Signature against AWS Nitro Root CA
+            // 3. Compare PCRs
+            log.info("[LiopVerifier] TEE Attestation: Not configured (no-op).");
+            return true;
+        }
+        catch (err) {
+            log.error("[LiopVerifier] TEE Verification Failed:", err);
+            return false;
+        }
+    }
+    /**
+     * Derives the ImageID of a logic payload following the LIOP v1 Standard.
+     */
+    deriveImageId(logicPayload) {
+        return deriveLogicImageDigest(logicPayload);
+    }
+}

package/dist/economy/estimator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TokenEstimator — Pluggable strategy for counting tokens in text content.
+ *
+ * Implementations range from exact BPE tokenization to lightweight heuristics,
+ * allowing the SDK to choose the best trade-off for the runtime environment.
+ */
+export interface TokenEstimator {
+    /** Count the number of tokens in the given text */
+    countTokens(text: string): number;
+    /** Human-readable name of the estimation strategy */
+    readonly name: string;
+}
+/**
+ * Exact BPE tokenizer using o200k_base encoding.
+ *
+ * o200k_base is the standard encoding for all modern OpenAI models
+ * (GPT-4o, GPT-4.1, o1, o3, o4) and provides a reasonable baseline
+ * for Anthropic/Google models as well (~±5% variance).
+ *
+ * - Synchronous: safe for hot-path usage without async overhead
+ * - Merge cache reduced to 10K entries for long-running server processes
+ * - Zero runtime dependencies beyond gpt-tokenizer itself
+ */
+export declare class RealTokenEstimator implements TokenEstimator {
+    readonly name = "o200k_base";
+    private countFn;
+    constructor(countFn: (text: string) => number, setMergeCacheSizeFn?: (size: number) => void);
+    countTokens(text: string): number;
+}
+/**
+ * Fallback heuristic estimator: ~4 characters per token.
+ *
+ * Industry-standard approximation (±10% for English/code content).
+ * Used only when gpt-tokenizer fails to load in constrained environments.
+ */
+export declare class HeuristicTokenEstimator implements TokenEstimator {
+    readonly name = "heuristic (chars/4)";
+    countTokens(text: string): number;
+}
+/**
+ * Factory: creates a RealTokenEstimator with gpt-tokenizer,
+ * falling back to HeuristicTokenEstimator if the import fails.
+ *
+ * Uses dynamic import to avoid blocking SDK initialization and to
+ * gracefully degrade in environments where gpt-tokenizer is unavailable.
+ */
+export declare function createTokenEstimator(): Promise<TokenEstimator>;
+/**
+ * Synchronous factory: creates a HeuristicTokenEstimator immediately.
+ * Used when the async factory cannot be awaited (e.g., constructor contexts).
+ * The engine should upgrade to the real estimator via setEstimator() later.
+ */
+export declare function createSyncTokenEstimator(): TokenEstimator;

package/dist/economy/estimator.js

@@ -0,0 +1,69 @@
+import { log } from "../utils/logger.js";
+/**
+ * Exact BPE tokenizer using o200k_base encoding.
+ *
+ * o200k_base is the standard encoding for all modern OpenAI models
+ * (GPT-4o, GPT-4.1, o1, o3, o4) and provides a reasonable baseline
+ * for Anthropic/Google models as well (~±5% variance).
+ *
+ * - Synchronous: safe for hot-path usage without async overhead
+ * - Merge cache reduced to 10K entries for long-running server processes
+ * - Zero runtime dependencies beyond gpt-tokenizer itself
+ */
+export class RealTokenEstimator {
+    name = "o200k_base";
+    countFn;
+    constructor(countFn, setMergeCacheSizeFn) {
+        this.countFn = countFn;
+        // Reduce merge cache from default 100K to 10K for server processes
+        if (setMergeCacheSizeFn) {
+            setMergeCacheSizeFn(10_000);
+        }
+    }
+    countTokens(text) {
+        if (text.length === 0)
+            return 0;
+        return this.countFn(text);
+    }
+}
+/**
+ * Fallback heuristic estimator: ~4 characters per token.
+ *
+ * Industry-standard approximation (±10% for English/code content).
+ * Used only when gpt-tokenizer fails to load in constrained environments.
+ */
+export class HeuristicTokenEstimator {
+    name = "heuristic (chars/4)";
+    countTokens(text) {
+        if (text.length === 0)
+            return 0;
+        return Math.ceil(text.length / 4);
+    }
+}
+/**
+ * Factory: creates a RealTokenEstimator with gpt-tokenizer,
+ * falling back to HeuristicTokenEstimator if the import fails.
+ *
+ * Uses dynamic import to avoid blocking SDK initialization and to
+ * gracefully degrade in environments where gpt-tokenizer is unavailable.
+ */
+export async function createTokenEstimator() {
+    try {
+        const mod = await import("gpt-tokenizer");
+        const estimator = new RealTokenEstimator(mod.countTokens, mod.setMergeCacheSize);
+        log.debug("[LIOP-Economy] Token estimator initialized: o200k_base");
+        return estimator;
+    }
+    catch {
+        log.info("[LIOP-Economy] gpt-tokenizer unavailable, falling back to heuristic estimator");
+        return new HeuristicTokenEstimator();
+    }
+}
+/**
+ * Synchronous factory: creates a HeuristicTokenEstimator immediately.
+ * Used when the async factory cannot be awaited (e.g., constructor contexts).
+ * The engine should upgrade to the real estimator via setEstimator() later.
+ */
+export function createSyncTokenEstimator() {
+    return new HeuristicTokenEstimator();
+}

package/dist/economy/index.d.ts

@@ -0,0 +1,5 @@
+export type { TokenEstimator } from "./estimator.js";
+export { createSyncTokenEstimator, createTokenEstimator, HeuristicTokenEstimator, RealTokenEstimator, } from "./estimator.js";
+export { LiopOTelBridge } from "./otel.js";
+export type { TokenOperationMetric, TokenSessionReport, ToolTokenBreakdown, } from "./telemetry.js";
+export { TokenTelemetryEngine } from "./telemetry.js";

package/dist/economy/index.js

@@ -0,0 +1,3 @@
+export { createSyncTokenEstimator, createTokenEstimator, HeuristicTokenEstimator, RealTokenEstimator, } from "./estimator.js";
+export { LiopOTelBridge } from "./otel.js";
+export { TokenTelemetryEngine } from "./telemetry.js";

package/dist/economy/otel.d.ts

@@ -0,0 +1,38 @@
+/**
+ * LiopOTelBridge — OpenTelemetry gen_ai.* metric emitter.
+ *
+ * Pattern: Library Instrumentation (uses global MeterProvider only).
+ * Per official OTel JS documentation:
+ * - Libraries MUST NOT create their own MeterProvider
+ * - Libraries SHOULD use metrics.getMeter() from the global API
+ * - If no MeterProvider is registered by the application, all operations are NoOp
+ *   with zero runtime overhead (confirmed by OTel JS source: NoopMeterProvider)
+ *
+ * Follows OpenTelemetry Generative AI Semantic Conventions (Development status).
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+export declare class LiopOTelBridge {
+    private tokenUsage;
+    private operationDuration;
+    private active;
+    constructor();
+    /**
+     * Record token usage with gen_ai.* standard attributes.
+     *
+     * @param tokens - Number of tokens consumed
+     * @param tokenType - "input" or "output" (gen_ai.token.type)
+     * @param operationName - gen_ai.operation.name (e.g., "execute_tool", "chat")
+     * @param toolName - Optional LIOP-specific tool name for attribution
+     */
+    recordTokens(tokens: number, tokenType: "input" | "output", operationName: string, toolName?: string): void;
+    /**
+     * Record operation duration with gen_ai.* standard attributes.
+     *
+     * @param durationMs - Duration in milliseconds (converted to seconds for OTel)
+     * @param operationName - gen_ai.operation.name
+     * @param error - Optional error type string if the operation failed
+     */
+    recordDuration(durationMs: number, operationName: string, error?: string): void;
+    /** Whether the OTel bridge is actively connected to a MeterProvider */
+    isActive(): boolean;
+}

package/dist/economy/otel.js

@@ -0,0 +1,100 @@
+import { metrics } from "@opentelemetry/api";
+import { log } from "../utils/logger.js";
+/** SDK identifier for the OTel Meter */
+const METER_NAME = "@nekzus/liop";
+const METER_VERSION = "1.2.0-alpha.9";
+/**
+ * gen_ai.client.token.usage — Recommended explicit bucket boundaries.
+ * Source: OpenTelemetry Generative AI Semantic Conventions (experimental).
+ */
+const TOKEN_USAGE_BUCKETS = [
+    1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304,
+    16777216, 67108864,
+];
+/**
+ * gen_ai.client.operation.duration — Recommended bucket boundaries (seconds).
+ * Source: OpenTelemetry Generative AI Semantic Conventions.
+ */
+const DURATION_BUCKETS = [
+    0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48,
+    40.96, 81.92,
+];
+/**
+ * LiopOTelBridge — OpenTelemetry gen_ai.* metric emitter.
+ *
+ * Pattern: Library Instrumentation (uses global MeterProvider only).
+ * Per official OTel JS documentation:
+ * - Libraries MUST NOT create their own MeterProvider
+ * - Libraries SHOULD use metrics.getMeter() from the global API
+ * - If no MeterProvider is registered by the application, all operations are NoOp
+ *   with zero runtime overhead (confirmed by OTel JS source: NoopMeterProvider)
+ *
+ * Follows OpenTelemetry Generative AI Semantic Conventions (Development status).
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+export class LiopOTelBridge {
+    tokenUsage;
+    operationDuration;
+    active = false;
+    constructor() {
+        try {
+            const meter = metrics.getMeter(METER_NAME, METER_VERSION);
+            this.tokenUsage = meter.createHistogram("gen_ai.client.token.usage", {
+                description: "Number of tokens used in LIOP Logic-on-Origin operations",
+                unit: "{token}",
+                advice: { explicitBucketBoundaries: TOKEN_USAGE_BUCKETS },
+            });
+            this.operationDuration = meter.createHistogram("gen_ai.client.operation.duration", {
+                description: "Duration of LIOP operations",
+                unit: "s",
+                advice: { explicitBucketBoundaries: DURATION_BUCKETS },
+            });
+            this.active = true;
+            log.debug("[LIOP-OTel] gen_ai.* metrics bridge initialized");
+        }
+        catch (err) {
+            // OTel API failed to load — degrade gracefully without affecting protocol
+            log.debug(`[LIOP-OTel] Bridge disabled: ${err instanceof Error ? err.message : String(err)}`);
+            const noopHistogram = {
+                record: () => { },
+            };
+            this.tokenUsage = noopHistogram;
+            this.operationDuration = noopHistogram;
+        }
+    }
+    /**
+     * Record token usage with gen_ai.* standard attributes.
+     *
+     * @param tokens - Number of tokens consumed
+     * @param tokenType - "input" or "output" (gen_ai.token.type)
+     * @param operationName - gen_ai.operation.name (e.g., "execute_tool", "chat")
+     * @param toolName - Optional LIOP-specific tool name for attribution
+     */
+    recordTokens(tokens, tokenType, operationName, toolName) {
+        this.tokenUsage.record(tokens, {
+            "gen_ai.system": "liop",
+            "gen_ai.operation.name": operationName,
+            "gen_ai.token.type": tokenType,
+            "gen_ai.request.model": "liop-mesh",
+            ...(toolName ? { "liop.tool.name": toolName } : {}),
+        });
+    }
+    /**
+     * Record operation duration with gen_ai.* standard attributes.
+     *
+     * @param durationMs - Duration in milliseconds (converted to seconds for OTel)
+     * @param operationName - gen_ai.operation.name
+     * @param error - Optional error type string if the operation failed
+     */
+    recordDuration(durationMs, operationName, error) {
+        this.operationDuration.record(durationMs / 1000, {
+            "gen_ai.system": "liop",
+            "gen_ai.operation.name": operationName,
+            ...(error ? { "error.type": error } : {}),
+        });
+    }
+    /** Whether the OTel bridge is actively connected to a MeterProvider */
+    isActive() {
+        return this.active;
+    }
+}

package/dist/economy/telemetry.d.ts

@@ -0,0 +1,77 @@
+/** Single MCP operation token footprint */
+export interface TokenOperationMetric {
+    readonly type: "tools_list" | "tool_call" | "resource_read" | "resource_list" | "prompt_get" | "prompt_list" | "diagnostic";
+    readonly method: string;
+    readonly estimatedInputTokens: number;
+    readonly estimatedOutputTokens: number;
+    readonly timestamp: number;
+    readonly toolName?: string;
+    readonly peerId?: string;
+    readonly durationMs?: number;
+}
+/** Session-level aggregate report */
+export interface TokenSessionReport {
+    readonly sessionId: string;
+    readonly operations: ReadonlyArray<TokenOperationMetric>;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly estimatorName: string;
+    readonly sessionUptimeMs: number;
+}
+/** Per-tool aggregate breakdown */
+export interface ToolTokenBreakdown {
+    readonly input: number;
+    readonly output: number;
+    readonly calls: number;
+    readonly avgDurationMs: number;
+}
+/**
+ * TokenTelemetryEngine — Full-spectrum observational singleton for token cost measurement.
+ *
+ * Design principles:
+ * - Pure observer pattern: NEVER mutates MCP payloads or protocol flow.
+ * - Real tokenization: o200k_base BPE via gpt-tokenizer (async init, sync counting).
+ * - OTel gen_ai.* emission: standard metrics via @opentelemetry/api (NoOp if no provider).
+ * - Error isolation: telemetry failures never propagate to protocol operations.
+ */
+export declare class TokenTelemetryEngine {
+    private static instance;
+    private operations;
+    private readonly sessionId;
+    private readonly startedAt;
+    private estimator;
+    private otelBridge;
+    private constructor();
+    /** Async upgrade from heuristic to real BPE tokenizer */
+    private initRealEstimator;
+    static getInstance(): TokenTelemetryEngine;
+    /**
+     * Count tokens in a string using the active estimator.
+     * Delegates to o200k_base BPE tokenizer (or heuristic fallback).
+     */
+    countTokens(content: string): number;
+    /**
+     * Record a single MCP operation's token footprint.
+     * Emits both internal metrics and OTel gen_ai.* histograms.
+     */
+    record(metric: Omit<TokenOperationMetric, "timestamp">): void;
+    /**
+     * @deprecated Use countTokens() instead. Kept for backward compatibility.
+     */
+    estimateTokens(content: string): number;
+    /** Generate the full session report */
+    getReport(): TokenSessionReport;
+    /** Get per-tool token breakdown for diagnostic display */
+    getPerToolReport(): Map<string, ToolTokenBreakdown>;
+    /**
+     * Format a rich, human-readable summary block for LiopMeshStatus diagnostic.
+     * Returns empty string when no operations have been recorded.
+     */
+    formatStatusBlock(): string;
+    /** Format milliseconds into human-readable uptime string */
+    private formatUptime;
+    /** Reset all recorded metrics (used in tests) */
+    reset(): void;
+    /** Destroy the singleton (used in tests to guarantee isolation) */
+    static destroy(): void;
+}

package/dist/economy/telemetry.js

@@ -0,0 +1,224 @@
+import { createSyncTokenEstimator, createTokenEstimator, } from "./estimator.js";
+import { LiopOTelBridge } from "./otel.js";
+/**
+ * Maps operation types to OTel gen_ai.operation.name values.
+ * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ */
+const OTEL_OPERATION_MAP = {
+    tools_list: "chat",
+    tool_call: "execute_tool",
+    resource_read: "chat",
+    resource_list: "chat",
+    prompt_get: "chat",
+    prompt_list: "chat",
+    diagnostic: "chat",
+};
+/**
+ * TokenTelemetryEngine — Full-spectrum observational singleton for token cost measurement.
+ *
+ * Design principles:
+ * - Pure observer pattern: NEVER mutates MCP payloads or protocol flow.
+ * - Real tokenization: o200k_base BPE via gpt-tokenizer (async init, sync counting).
+ * - OTel gen_ai.* emission: standard metrics via @opentelemetry/api (NoOp if no provider).
+ * - Error isolation: telemetry failures never propagate to protocol operations.
+ */
+export class TokenTelemetryEngine {
+    static instance = null;
+    operations = [];
+    sessionId;
+    startedAt;
+    estimator;
+    otelBridge;
+    constructor() {
+        this.sessionId = crypto.randomUUID();
+        this.startedAt = Date.now();
+        // Start with sync heuristic estimator (available immediately)
+        this.estimator = createSyncTokenEstimator();
+        this.otelBridge = new LiopOTelBridge();
+        // Upgrade to real tokenizer asynchronously
+        this.initRealEstimator();
+    }
+    /** Async upgrade from heuristic to real BPE tokenizer */
+    initRealEstimator() {
+        createTokenEstimator()
+            .then((real) => {
+            this.estimator = real;
+        })
+            .catch(() => {
+            // Keep heuristic fallback — already assigned in constructor
+        });
+    }
+    static getInstance() {
+        if (!TokenTelemetryEngine.instance) {
+            TokenTelemetryEngine.instance = new TokenTelemetryEngine();
+        }
+        return TokenTelemetryEngine.instance;
+    }
+    /**
+     * Count tokens in a string using the active estimator.
+     * Delegates to o200k_base BPE tokenizer (or heuristic fallback).
+     */
+    countTokens(content) {
+        try {
+            return this.estimator.countTokens(content);
+        }
+        catch {
+            // Fallback: never let counting failures break protocol flow
+            return Math.ceil(content.length / 4);
+        }
+    }
+    /**
+     * Record a single MCP operation's token footprint.
+     * Emits both internal metrics and OTel gen_ai.* histograms.
+     */
+    record(metric) {
+        const fullMetric = {
+            ...metric,
+            timestamp: Date.now(),
+        };
+        this.operations.push(fullMetric);
+        // Emit to OTel bridge (NoOp if no MeterProvider configured)
+        try {
+            const otelOp = OTEL_OPERATION_MAP[metric.type] || "chat";
+            if (metric.estimatedInputTokens > 0) {
+                this.otelBridge.recordTokens(metric.estimatedInputTokens, "input", otelOp, metric.toolName);
+            }
+            if (metric.estimatedOutputTokens > 0) {
+                this.otelBridge.recordTokens(metric.estimatedOutputTokens, "output", otelOp, metric.toolName);
+            }
+            if (metric.durationMs !== undefined) {
+                this.otelBridge.recordDuration(metric.durationMs, otelOp);
+            }
+        }
+        catch {
+            // OTel emission failure must never affect protocol operations
+        }
+    }
+    /**
+     * @deprecated Use countTokens() instead. Kept for backward compatibility.
+     */
+    estimateTokens(content) {
+        return this.countTokens(content);
+    }
+    /** Generate the full session report */
+    getReport() {
+        return {
+            sessionId: this.sessionId,
+            operations: [...this.operations],
+            totalInputTokens: this.operations.reduce((sum, op) => sum + op.estimatedInputTokens, 0),
+            totalOutputTokens: this.operations.reduce((sum, op) => sum + op.estimatedOutputTokens, 0),
+            estimatorName: this.estimator.name,
+            sessionUptimeMs: Date.now() - this.startedAt,
+        };
+    }
+    /** Get per-tool token breakdown for diagnostic display */
+    getPerToolReport() {
+        const breakdown = new Map();
+        for (const op of this.operations) {
+            const key = op.toolName || op.method;
+            const existing = breakdown.get(key) || {
+                input: 0,
+                output: 0,
+                calls: 0,
+                avgDurationMs: 0,
+            };
+            const totalDuration = existing.avgDurationMs * existing.calls + (op.durationMs || 0);
+            const newCalls = existing.calls + 1;
+            breakdown.set(key, {
+                input: existing.input + op.estimatedInputTokens,
+                output: existing.output + op.estimatedOutputTokens,
+                calls: newCalls,
+                avgDurationMs: newCalls > 0 ? totalDuration / newCalls : 0,
+            });
+        }
+        return breakdown;
+    }
+    /**
+     * Format a rich, human-readable summary block for LiopMeshStatus diagnostic.
+     * Returns empty string when no operations have been recorded.
+     */
+    formatStatusBlock() {
+        const report = this.getReport();
+        if (report.operations.length === 0)
+            return "";
+        const uptimeStr = this.formatUptime(report.sessionUptimeMs);
+        const totalCombined = report.totalInputTokens + report.totalOutputTokens;
+        // Aggregate operations by type
+        const byType = new Map();
+        for (const op of report.operations) {
+            const key = op.type;
+            const existing = byType.get(key) || {
+                count: 0,
+                input: 0,
+                output: 0,
+            };
+            byType.set(key, {
+                count: existing.count + 1,
+                input: existing.input + op.estimatedInputTokens,
+                output: existing.output + op.estimatedOutputTokens,
+            });
+        }
+        // Build type breakdown lines
+        const typeEntries = Array.from(byType.entries());
+        const typeLines = typeEntries.map(([type, data], idx) => {
+            const prefix = idx === typeEntries.length - 1 ? "│  └─" : "│  ├─";
+            const outputPart = data.output > 0 ? ` / ${data.output.toLocaleString()} out` : "";
+            return `${prefix} ${type} ×${data.count} → ${data.input.toLocaleString()} in${outputPart}`;
+        });
+        // Build per-tool breakdown
+        const toolReport = this.getPerToolReport();
+        const toolEntries = Array.from(toolReport.entries()).filter(([key]) => key !== "tools/list" && key !== "LiopMeshStatus");
+        const toolLines = [];
+        if (toolEntries.length > 0) {
+            toolLines.push("├─ By Tool:");
+            toolEntries.forEach(([name, data], idx) => {
+                const prefix = idx === toolEntries.length - 1 ? "│  └─" : "│  ├─";
+                const outputPart = data.output > 0 ? ` / ${data.output.toLocaleString()} out` : "";
+                const durationPart = data.avgDurationMs > 0 ? ` ~${Math.round(data.avgDurationMs)}ms` : "";
+                toolLines.push(`${prefix} ${name}: ${data.input.toLocaleString()} in${outputPart} (×${data.calls})${durationPart}`);
+            });
+        }
+        // Calculate average latency across all timed operations
+        const timedOps = report.operations.filter((op) => op.durationMs !== undefined);
+        const avgLatency = timedOps.length > 0
+            ? Math.round(timedOps.reduce((sum, op) => sum + (op.durationMs || 0), 0) /
+                timedOps.length)
+            : 0;
+        const otelStatus = this.otelBridge.isActive()
+            ? "gen_ai.client.token.usage → active"
+            : "disabled";
+        const lines = [
+            "\nToken Economy:",
+            `├─ Session: ${report.sessionId.slice(0, 8)} (${uptimeStr})`,
+            `├─ Estimator: ${report.estimatorName}`,
+            `├─ Operations: ${report.operations.length}`,
+            ...typeLines,
+            `├─ Total: ${report.totalInputTokens.toLocaleString()} in / ${report.totalOutputTokens.toLocaleString()} out (${totalCombined.toLocaleString()} combined)`,
+            ...toolLines,
+            ...(avgLatency > 0 ? [`├─ Avg Latency: ${avgLatency}ms`] : []),
+            `└─ OTel: ${otelStatus}`,
+        ];
+        return lines.join("\n");
+    }
+    /** Format milliseconds into human-readable uptime string */
+    formatUptime(ms) {
+        const seconds = Math.floor(ms / 1000);
+        if (seconds < 60)
+            return `${seconds}s`;
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = seconds % 60;
+        if (minutes < 60)
+            return `${minutes}m ${remainingSeconds}s`;
+        const hours = Math.floor(minutes / 60);
+        const remainingMinutes = minutes % 60;
+        return `${hours}h ${remainingMinutes}m`;
+    }
+    /** Reset all recorded metrics (used in tests) */
+    reset() {
+        this.operations = [];
+    }
+    /** Destroy the singleton (used in tests to guarantee isolation) */
+    static destroy() {
+        TokenTelemetryEngine.instance = null;
+    }
+}