@nekzus/liop 1.2.0-alpha.9 → 1.2.0

package/dist/client/index.js

@@ -3,6 +3,7 @@ import { MeshNode, } from "../mesh/node.js";
 import { LiopRpcClient } from "../rpc/client.js";
 import { AesGcmWrapper } from "../rpc/crypto/aes.js";
 import { Kyber768Wrapper } from "../rpc/crypto/kyber.js";
+import { log } from "../utils/logger.js";
 /**
  * LIOP Client
  * High-level orchestration for discovery and execution in the Logic-Injection-on-Origin mesh.
@@ -24,11 +25,11 @@ export class LiopClient {
     async connect(address, options) {
         this.meshNode = new MeshNode(options?.meshConfig);
         await this.meshNode.start();
-        console.error(`[LiopClient] Mesh Node synchronized. PeerID: ${this.meshNode.getPeerId()}`);
+        log.info(`[LiopClient] Mesh Node synchronized. PeerID: ${this.meshNode.getPeerId()}`);
         if (address) {
             this.rpcClients.set("static", new LiopRpcClient(address, this.tlsOptions));
             this.serverInfo = { name: `LiopServer (${address})`, version: "1.0.0" };
-            console.error(`[LiopClient] Static gRPC configured for: ${address}`);
+            log.info(`[LiopClient] Static gRPC configured for: ${address}`);
         }
         else {
             this.serverInfo = { name: "LiopServer (Mesh Alpha)", version: "1.0.0" };
@@ -41,25 +42,25 @@ export class LiopClient {
     async resolveCapability(toolName) {
         if (!this.meshNode)
             throw new Error("Client must be connected to Mesh to resolve capabilities.");
-        console.error(`[LiopClient] Querying Mesh DHT for Provider: ${toolName}...`);
+        log.info(`[LiopClient] Querying Mesh DHT for Provider: ${toolName}...`);
         const providers = await this.meshNode.findProviders(toolName);
         if (providers.length === 0) {
             throw new Error(`Kademlia DHT found zero providers for capability: ${toolName}`);
         }
         const providerId = providers[0];
-        console.error(`[LiopClient] Identified Alpha Provider PeerID: ${providerId}`);
+        log.info(`[LiopClient] Identified Alpha Provider PeerID: ${providerId}`);
         let grpcPort = 50051;
         const manifest = await this.meshNode.queryManifest(providerId);
         if (manifest) {
             grpcPort = manifest.grpcPort;
-            console.error(`[LiopClient] Manifest resolved: gRPC port ${grpcPort}`);
+            log.info(`[LiopClient] Manifest resolved: gRPC port ${grpcPort}`);
         }
         const addrs = await this.meshNode.resolvePeer(providerId);
         for (const maddr of addrs) {
             const parts = maddr.split("/");
             if (parts[1] === "ip4") {
                 const grpcHost = `${parts[2]}:${grpcPort}`;
-                console.error(`[LiopClient] Translated Multiaddr to gRPC Target: ${grpcHost}`);
+                log.info(`[LiopClient] Translated Multiaddr to gRPC Target: ${grpcHost}`);
                 return grpcHost;
             }
         }
@@ -72,13 +73,13 @@ export class LiopClient {
         if (!this.meshNode) {
             throw new Error("Client must be connected before discovering tools.");
         }
-        console.error(`[LiopClient] Discovery started...`);
+        log.info(`[LiopClient] Discovery started...`);
         const providerIds = await this.meshNode.discoverManifestProviders();
         const tools = [];
         const seenNames = new Set();
         for (const peerId of providerIds) {
             try {
-                console.error(`[LiopClient] Querying manifest from: ${peerId}`);
+                log.info(`[LiopClient] Querying manifest from: ${peerId}`);
                 const manifest = await this.meshNode.queryManifest(peerId);
                 if (manifest) {
                     this.manifests.set(peerId, manifest);
@@ -91,10 +92,10 @@ export class LiopClient {
                 }
             }
             catch (err) {
-                console.error(`[LiopClient] Error querying manifest from ${peerId}:`, err instanceof Error ? err.message : String(err));
+                log.info(`[LiopClient] Error querying manifest from ${peerId}:`, err instanceof Error ? err.message : String(err));
             }
         }
-        console.error(`[LiopClient] Discovery finished. Found ${tools.length} unique tools.`);
+        log.info(`[LiopClient] Discovery finished. Found ${tools.length} unique tools.`);
         return tools;
     }
     /**
@@ -105,7 +106,7 @@ export class LiopClient {
             throw new Error("Client must be connected before calling tools.");
         }
         const toolName = request.name;
-        console.error(`[LiopClient] Resolving Tool: ${toolName}`);
+        log.info(`[LiopClient] Resolving Tool: ${toolName}`);
         // [ALPHA-FIX] Bypass DHT discovery if we are already statically connected to a provider (Enterprise/Test mode)
         let rpcClient = this.rpcClients.get("static");
         if (!rpcClient) {
@@ -113,13 +114,20 @@ export class LiopClient {
             rpcClient = this.getOrCreateRpcClient(toolName, dynamicAddress);
         }
         else {
-            console.error(`[LiopClient] Using existing static gRPC connection for ${toolName}.`);
+            log.info(`[LiopClient] Using existing static gRPC connection for ${toolName}.`);
         }
-        console.error(`[LiopClient] Negotiating intent for ${toolName}...`);
+        log.info(`[LiopClient] Negotiating intent for ${toolName}...`);
+        const agentDid = this.meshNode
+            ? `did:liop:${this.meshNode.getPeerId()}`
+            : "did:liop:ephemeral";
+        const intentPayload = Buffer.from(`${toolName}:${Date.now()}`);
+        const proofOfIntent = this.meshNode
+            ? await this.meshNode.sign(intentPayload)
+            : intentPayload;
         const intentResponse = (await rpcClient.negotiateIntent({
-            agent_did: "liop-client-alpha",
+            agent_did: agentDid,
             capability_hash: toolName,
-            proof_of_intent: Buffer.from("alpha-intent-proof"),
+            proof_of_intent: proofOfIntent,
         }));
         if (!intentResponse.accepted) {
             throw new Error(`Intent denied by host: ${intentResponse.error_message}`);
@@ -128,14 +136,14 @@ export class LiopClient {
         const publicKey = intentResponse.kyber_public_key || intentResponse.kyberPublicKey;
         const sessionToken = intentResponse.session_token || intentResponse.sessionToken;
         if (!publicKey) {
-            console.error("[LiopClient] Critical Error: Kyber Public Key not found in IntentResponse.", intentResponse);
+            log.info("[LiopClient] Critical Error: Kyber Public Key not found in IntentResponse.", intentResponse);
             throw new Error("Handshake failed: Remote host did not provide a valid Kyber Public Key.");
         }
         // 2. Post-Quantum Encapsulation (ML-KEM-768)
-        console.error(`[LiopClient] Encapsulating Post-Quantum Shared Secret for ${request.name}...`);
+        log.info(`[LiopClient] Encapsulating Post-Quantum Shared Secret for ${request.name}...`);
         const { ciphertext: kyberCiphertext, sharedSecret } = await Kyber768Wrapper.encapsulateAsymmetric(publicKey);
         // 3. Symmetric Sealing (AES-256-GCM)
-        console.error(`[LiopClient] Sealing WASM Payload and Inputs...`);
+        log.info(`[LiopClient] Sealing WASM Payload and Inputs...`);
         const _safePayload = _wasmPayload || Buffer.from("");
         // Encrypt WASM binary
         const { ciphertext: encryptedWasm, nonce: aesNonce } = AesGcmWrapper.encryptPayload(_safePayload, sharedSecret);
@@ -173,7 +181,7 @@ export class LiopClient {
                 if (resultFulfilled)
                     return;
                 hasReceivedData = true;
-                console.error("[LiopClient] Logic Executed. Verification in progress...");
+                log.info("[LiopClient] Logic Executed. Verification in progress...");
                 try {
                     const isValid = await this.verifier.verifyZkReceipt(_safePayload, Buffer.from(response.cryptographic_proof).toString("hex"), Buffer.from(response.zk_receipt));
                     if (!isValid) {
@@ -198,7 +206,7 @@ export class LiopClient {
             stream.on("error", (err) => {
                 if (resultFulfilled)
                     return;
-                console.error("[LiopClient] Stream Error:", err);
+                log.error("[LiopClient] Stream Error:", err);
                 reject(err);
             });
             stream.on("end", () => {
@@ -226,26 +234,29 @@ export class LiopClient {
         if (!this.meshNode) {
             throw new Error("Client must be connected before reading resources.");
         }
-        console.error(`[LiopClient] Querying Mesh for Resource: ${uri}...`);
-        // For now, in Alpha v3, we assume the resource is provided by an active provider.
-        // A more complex implementation would use resolveCapability(uri).
-        // For the industrial demo, we'll simulate a direct read if connected or throw.
-        const rpcClient = this.rpcClients.get("static") || Array.from(this.rpcClients.values())[0];
-        if (!rpcClient) {
-            throw new Error("Resource reading requires an active RPC connection to a provider.");
+        log.info(`[LiopClient] Querying Mesh for Resource: ${uri}...`);
+        // We search for the peer hosting the resource in the P2P Mesh
+        const providers = await this.meshNode.findProviders(uri);
+        if (providers.length === 0) {
+            throw new Error(`No mesh providers found for resource: ${uri}`);
+        }
+        // Query the remote peer's manifest
+        const manifest = await this.meshNode.queryManifest(providers[0]);
+        if (!manifest) {
+            throw new Error("Target peer did not return a valid LIOP Manifest.");
+        }
+        // Locate the exact resource metadata
+        const resourceDef = manifest.resources?.find((r) => r.uri === uri);
+        if (!resourceDef) {
+            throw new Error(`Resource ${uri} not listed in remote manifest.`);
         }
-        // This emulates the resource retrieval.
-        // In a full implementation, this might be a gRPC call.
+        // Return the declarative metadata (Logic-Injection is required for actual data extraction)
         return {
             contents: [
                 {
                     uri,
-                    mimeType: "application/json",
-                    text: JSON.stringify({
-                        status: "Alpha-Resource-Read-Success",
-                        uri,
-                        timestamp: new Date().toISOString(),
-                    }),
+                    mimeType: resourceDef.mimeType || "application/json",
+                    text: JSON.stringify(resourceDef, null, 2),
                 },
             ],
         };

package/dist/crypto/logic-image-id.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeLogicSource(logicUtf8: string): string;
+/** SHA-256 digest of logic bytes (WASM raw; JS UTF-8 after top-level envelope strip). */
+export declare function deriveLogicImageDigest(logicPayload: Uint8Array): Buffer;

package/dist/crypto/logic-image-id.js

@@ -0,0 +1,27 @@
+import crypto from "node:crypto";
+/**
+ * Top-level LIOP v1 envelope only. Must NOT use multiline (^/$) mode:
+ * proxy logic embeds a full envelope inside JSON strings; `^` per line would
+ * incorrectly treat that as the document root and desync ImageID vs the worker.
+ */
+const TOP_LEVEL_ENVELOPE = /^\s*@LIOP\{[^}]+\}\n?([\s\S]*?)\n?@END\s*$/;
+export function normalizeLogicSource(logicUtf8) {
+    const match = logicUtf8.match(TOP_LEVEL_ENVELOPE);
+    if (match?.[1] !== undefined) {
+        return match[1].trim();
+    }
+    return logicUtf8.trim();
+}
+/** SHA-256 digest of logic bytes (WASM raw; JS UTF-8 after top-level envelope strip). */
+export function deriveLogicImageDigest(logicPayload) {
+    const isWasm = logicPayload[0] === 0x00 && logicPayload[1] === 0x61;
+    if (isWasm) {
+        return crypto.createHash("sha256").update(logicPayload).digest();
+    }
+    const text = Buffer.from(logicPayload).toString("utf-8");
+    const normalized = normalizeLogicSource(text);
+    return crypto
+        .createHash("sha256")
+        .update(Buffer.from(normalized, "utf-8"))
+        .digest();
+}

package/dist/crypto/verifier.js

@@ -1,8 +1,9 @@
-import crypto from "node:crypto";
 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);
 /**
@@ -59,10 +60,10 @@ export class LiopVerifier {
             zkReceipt: new Uint8Array(zkReceipt),
         });
         if (result.verified) {
-            console.error(`[LiopVerifier] ${result.message}`);
+            log.info(`[LiopVerifier] ${result.message}`);
             return true;
         }
-        console.error(`[LiopVerifier] FAILED: ${result.message}`);
+        log.error(`[LiopVerifier] FAILED: ${result.message}`);
         return false;
     }
     /**
@@ -78,11 +79,11 @@ export class LiopVerifier {
             // 1. Decode CBOR/COSE
             // 2. Verify Signature against AWS Nitro Root CA
             // 3. Compare PCRs
-            console.error("[LiopVerifier] TEE Attestation: AWS Nitro Enclave Signature Verified.");
+            log.info("[LiopVerifier] TEE Attestation: Not configured (no-op).");
             return true;
         }
         catch (err) {
-            console.error("[LiopVerifier] TEE Verification Failed:", err);
+            log.error("[LiopVerifier] TEE Verification Failed:", err);
             return false;
         }
     }
@@ -90,19 +91,6 @@ export class LiopVerifier {
      * Derives the ImageID of a logic payload following the LIOP v1 Standard.
      */
     deriveImageId(logicPayload) {
-        // Sanitization logic for JS payloads (Magic headers, etc.)
-        let processed = logicPayload;
-        const isWasm = logicPayload[0] === 0x00 && logicPayload[1] === 0x61; // \0asm
-        if (!isWasm) {
-            const text = logicPayload.toString("utf-8");
-            const clean = text
-                .replace(/^LIOP_MAGIC:.*?\n/g, "")
-                .replace(/^MANIFEST:.*?\n/g, "")
-                .replace(/---BEGIN_LOGIC---\n?/g, "")
-                .replace(/\n?---END_LOGIC---/g, "")
-                .trim();
-            processed = Buffer.from(clean);
-        }
-        return crypto.createHash("sha256").update(processed).digest();
+        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;
+}