@nekzus/liop 1.2.0-alpha.9 → 1.3.0-alpha.1

package/dist/bridge/stream.js

@@ -3,6 +3,7 @@ import { serve } from "@hono/node-server";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
+import { log } from "../utils/logger.js";
 import { LiopMcpBridge } from "./index.js";
 const DEFAULT_MAX_SESSIONS_PER_IP = 10;
 const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
@@ -53,7 +54,7 @@ export class LiopStreamBridge {
                     lastActivity: Date.now(),
                     clientIp,
                 });
-                console.error(`[LIOP-StreamBridge] Session opened: ${sessionId} (IP: ${clientIp})`);
+                log.info(`[LIOP-StreamBridge] Session opened: ${sessionId} (IP: ${clientIp})`);
             },
         });
         // Wire the transport's incoming messages to the LiopMcpBridge JSON-RPC router
@@ -72,13 +73,13 @@ export class LiopStreamBridge {
                 }
             }
             catch (err) {
-                console.error("[LIOP-StreamBridge] JSON-RPC error:", err.message);
+                log.info("[LIOP-StreamBridge] JSON-RPC error:", err.message);
             }
         };
         transport.onclose = () => {
             if (transport.sessionId) {
                 this.activeSessions.delete(transport.sessionId);
-                console.error(`[LIOP-StreamBridge] Session closed: ${transport.sessionId}`);
+                log.info(`[LIOP-StreamBridge] Session closed: ${transport.sessionId}`);
             }
         };
         return transport;
@@ -109,7 +110,7 @@ export class LiopStreamBridge {
         const now = Date.now();
         for (const [sessionId, entry] of this.activeSessions) {
             if (now - entry.lastActivity > this.sessionTimeoutMs) {
-                console.error(`[LIOP-StreamBridge] Evicting idle session: ${sessionId}`);
+                log.info(`[LIOP-StreamBridge] Evicting idle session: ${sessionId}`);
                 entry.transport.close().catch(() => {
                     /* Swallow close errors */
                 });
@@ -119,17 +120,24 @@ export class LiopStreamBridge {
     }
     setupRoutes() {
         this.app.use("*", cors());
+        // Initialize strict zero-trust token if not provided
+        if (!process.env.ZERO_TRUST_TOKEN) {
+            process.env.ZERO_TRUST_TOKEN = randomUUID();
+            log.info("=".repeat(60));
+            log.info("⚠️ STRICT ZERO-TRUST MODE ENABLED ⚠️");
+            log.info("No ZERO_TRUST_TOKEN found in environment.");
+            log.info("A secure ephemeral token has been generated for this session:");
+            log.info(`Token: ${process.env.ZERO_TRUST_TOKEN}`);
+            log.info("=".repeat(60));
+        }
         // ZTA (Zero-Trust Architecture) Security Middleware
         this.app.use("/mcp", async (c, next) => {
             const auth = c.req.header("Authorization");
             const expectedToken = process.env.ZERO_TRUST_TOKEN;
-            if (expectedToken) {
-                if (!auth ||
-                    !auth.startsWith("Bearer ") ||
-                    auth.split(" ")[1] !== expectedToken) {
-                    console.error("[LIOP-StreamBridge] ALERT: Access denied - Invalid Zero-Trust token.");
-                    return c.json({ error: "Unauthorized: LIOP Zero-Trust Policy Enforced" }, 401);
-                }
+            if (!auth?.startsWith("Bearer ") ||
+                auth.split(" ")[1] !== expectedToken) {
+                log.info("[LIOP-StreamBridge] ALERT: Access denied - Invalid Zero-Trust token.");
+                return c.json({ error: "Unauthorized: LIOP Zero-Trust Policy Enforced" }, 401);
             }
             await next();
         });
@@ -149,7 +157,7 @@ export class LiopStreamBridge {
                 // Explicitly clean up the session from the Map.
                 if (c.req.method === "DELETE") {
                     this.activeSessions.delete(sessionId);
-                    console.error(`[LIOP-StreamBridge] Session closed (DELETE): ${sessionId}`);
+                    log.info(`[LIOP-StreamBridge] Session closed (DELETE): ${sessionId}`);
                 }
                 return response;
             }
@@ -158,7 +166,7 @@ export class LiopStreamBridge {
             const clientIp = this.getClientIp(c);
             const currentSessions = this.countSessionsByIp(clientIp);
             if (currentSessions >= this.maxSessionsPerIp) {
-                console.error(`[LIOP-StreamBridge] Rate limit hit for IP: ${clientIp} (${currentSessions} sessions)`);
+                log.info(`[LIOP-StreamBridge] Rate limit hit for IP: ${clientIp} (${currentSessions} sessions)`);
                 return c.json({ error: "Too Many Sessions: Rate limit exceeded" }, 429);
             }
             const transport = this.createSessionTransport(clientIp);
@@ -177,7 +185,7 @@ export class LiopStreamBridge {
                 fetch: this.app.fetch,
                 port: listenPort,
             }, (info) => {
-                console.error(`[LIOP-StreamBridge] Streamable HTTP Gateway on http://localhost:${info.port}/mcp`);
+                log.info(`[LIOP-StreamBridge] Streamable HTTP Gateway on http://localhost:${info.port}/mcp`);
                 resolve();
             });
         });
@@ -196,7 +204,7 @@ export class LiopStreamBridge {
         }
         if (this.httpServer) {
             this.httpServer.close();
-            console.error("[LIOP-StreamBridge] HTTP ports released.");
+            log.info("[LIOP-StreamBridge] HTTP ports released.");
         }
     }
 }

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,30 +136,30 @@ 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);
-        // Encrypt inputs using the SAME session nonce for the multi-payload request (Standard LIOP V1)
+        // Encrypt inputs using a fresh random nonce per input to prevent AES-GCM nonce reuse
         const encryptedInputs = {};
+        const crypto = await import("node:crypto");
         for (const [key, value] of Object.entries(request.arguments || {})) {
-            // We manually encrypt with the same nonce/key to match the Proto structure
-            // ideally we'd have per-field nonces, but for Alpha we follow the liop_core.proto v1.
-            const crypto = await import("node:crypto");
-            const cipher = crypto.createCipheriv("aes-256-gcm", sharedSecret, aesNonce);
+            const inputNonce = crypto.randomBytes(12);
+            const cipher = crypto.createCipheriv("aes-256-gcm", sharedSecret, inputNonce);
             const encrypted = Buffer.concat([
                 cipher.update(JSON.stringify(value)),
                 cipher.final(),
             ]);
             const authTag = cipher.getAuthTag();
-            encryptedInputs[key] = Buffer.concat([encrypted, authTag]);
+            // Prepend the 12-byte nonce to the ciphertext
+            encryptedInputs[key] = Buffer.concat([inputNonce, encrypted, authTag]);
         }
         // 4. Assemble and Execute gRPC LogicRequest
         const logicRequest = {
@@ -173,9 +181,9 @@ 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));
+                    const isValid = await this.verifier.verifyZkReceipt(_safePayload, Buffer.from(response.cryptographic_proof).toString("hex"), Buffer.from(response.zk_receipt), Buffer.from(sharedSecret));
                     if (!isValid) {
                         reject(new Error("PROTOCOL INTEGRITY VIOLATION: ZK-Receipt verification failed."));
                         return;
@@ -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.d.ts

@@ -15,7 +15,7 @@ export declare class LiopVerifier {
      * @param remoteImageIdHex The ImageID reported by the provider (must match our local calculation).
      * @param zkReceipt The mathematical proof (Seal + Journal) from the zkVM.
      */
-    verifyZkReceipt(logicPayload: Buffer, remoteImageIdHex: string, zkReceipt: Buffer): Promise<boolean>;
+    verifyZkReceipt(logicPayload: Buffer, remoteImageIdHex: string, zkReceipt: Buffer, sessionSecret?: Buffer): Promise<boolean>;
     /**
      * Verifies if a node is running inside an authenticated TEE (e.g. AWS Nitro).
      *

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);
 /**
@@ -48,7 +49,7 @@ export class LiopVerifier {
      * @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) {
+    async verifyZkReceipt(logicPayload, remoteImageIdHex, zkReceipt, sessionSecret) {
         const pool = this.getZkPool();
         if (!pool)
             throw new Error("Worker pool initialization failed");
@@ -57,12 +58,13 @@ export class LiopVerifier {
             logicPayload: new Uint8Array(logicPayload),
             remoteImageIdHex,
             zkReceipt: new Uint8Array(zkReceipt),
+            sessionSecret: sessionSecret ? new Uint8Array(sessionSecret) : undefined,
         });
         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 +80,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 +92,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;
+}