@nekzus/liop 1.2.0-alpha.9 → 1.2.0

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;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export declare enum ErrorCode {
+    CapabilityViolation = "CapabilityViolation",
+    SandboxEscape = "SandboxEscape",
+    PiiLeak = "PiiLeak",
+    InvalidIntent = "InvalidIntent",
+    Throttled = "Throttled",
+    ZkVerificationFailed = "ZkVerificationFailed",
+    MeshUnavailable = "MeshUnavailable",
+    ConnectionFailed = "ConnectionFailed"
+}
+export declare class LiopError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,19 @@
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["CapabilityViolation"] = "CapabilityViolation";
+    ErrorCode["SandboxEscape"] = "SandboxEscape";
+    ErrorCode["PiiLeak"] = "PiiLeak";
+    ErrorCode["InvalidIntent"] = "InvalidIntent";
+    ErrorCode["Throttled"] = "Throttled";
+    ErrorCode["ZkVerificationFailed"] = "ZkVerificationFailed";
+    ErrorCode["MeshUnavailable"] = "MeshUnavailable";
+    ErrorCode["ConnectionFailed"] = "ConnectionFailed";
+})(ErrorCode || (ErrorCode = {}));
+export class LiopError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LiopError";
+        this.code = code;
+    }
+}

package/dist/gateway/hybrid.d.ts

@@ -1,5 +1,6 @@
 import type { MeshNode } from "../mesh/index.js";
 import type { LiopServer } from "../server/index.js";
+import { LiopMcpRouter } from "./router.js";
 /**
  * LIOP Hybrid Gateway
  * High-level orchestration for connecting MCP (JSON-RPC) clients to the LIOP Mesh.
@@ -16,6 +17,7 @@ export declare class LiopHybridGateway {
     private setupH1Routes;
     private handleGrpcStream;
     private handleMcpH2Stream;
-    listen(port: number, host?: string): Promise<void>;
+    listen(port: number, host?: string): Promise<number>;
     stop(): Promise<void>;
+    getRouter(): LiopMcpRouter;
 }

package/dist/gateway/hybrid.js

@@ -1,6 +1,7 @@
 import * as http from "node:http";
 import * as http2 from "node:http2";
 import * as net from "node:net";
+import { log } from "../utils/logger.js";
 import { LiopMcpRouter } from "./router.js";
 /**
  * LIOP Hybrid Gateway
@@ -28,7 +29,7 @@ export class LiopHybridGateway {
         this.netServer = net.createServer((socket) => {
             socket.once("data", (buffer) => {
                 const isHttp2 = buffer.toString().startsWith("PRI * HTTP/2.0");
-                console.error(`[LIOP-Gateway] Incoming L4 Connection. Protocol: ${isHttp2 ? "HTTP/2 (gRPC)" : "HTTP/1.1 (MCP)"}`);
+                log.info(`[LIOP-Gateway] Incoming L4 Connection. Protocol: ${isHttp2 ? "HTTP/2 (gRPC)" : "HTTP/1.1 (MCP)"}`);
                 if (isHttp2) {
                     this.h2Server.emit("connection", socket);
                 }
@@ -37,12 +38,12 @@ export class LiopHybridGateway {
                 }
                 socket.unshift(buffer);
             });
-            socket.on("error", (err) => console.error(`[LIOP-Gateway] NetServer Socket Error: ${err.message}`));
+            socket.on("error", (err) => log.error(`[LIOP-Gateway] NetServer Socket Error: ${err.message}`));
         });
         // Attach error listeners to sub-servers to catch silent failures
-        this.h1Server.on("error", (err) => console.error(`[LIOP-Gateway] H1 Server Error: ${err.message}`));
-        this.h2Server.on("error", (err) => console.error(`[LIOP-Gateway] H2 Server Error: ${err.message}`));
-        console.error("[LIOP-Gateway] Hybrid adapter initialized.");
+        this.h1Server.on("error", (err) => log.error(`[LIOP-Gateway] H1 Server Error: ${err.message}`));
+        this.h2Server.on("error", (err) => log.error(`[LIOP-Gateway] H2 Server Error: ${err.message}`));
+        log.info("[LIOP-Gateway] Hybrid adapter initialized.");
     }
     setupH2Routes() {
         this.h2Server.on("stream", (stream, headers) => {
@@ -62,6 +63,26 @@ export class LiopHybridGateway {
             const method = req.method;
             if (method === "GET" &&
                 (url === "/" || url === "/mcp" || url === "/health")) {
+                if (url === "/health" &&
+                    req.headers.accept?.includes("application/json")) {
+                    const meshInfo = this.meshNode
+                        ? {
+                            peerId: this.meshNode.getPeerId()?.toString() || "",
+                            multiaddrs: this.meshNode
+                                .getMultiaddrs()
+                                .map((m) => m.toString()),
+                        }
+                        : null;
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({
+                        status: "healthy",
+                        node: this.liopServer.getServerInfo(),
+                        mesh: meshInfo,
+                        tools: this.liopServer.listTools().map((t) => t.name),
+                        timestamp: new Date().toISOString(),
+                    }));
+                    return;
+                }
                 res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
                 res.end(`
                     <body style="background:#0f172a;color:#f8fafc;font-family:sans-serif;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100vh;margin:0">
@@ -88,7 +109,7 @@ export class LiopHybridGateway {
                         res.end(JSON.stringify(response));
                     }
                     catch (e) {
-                        console.error(`[LIOP-Gateway] Error processing JSON-RPC payload: ${e.message}`);
+                        log.info(`[LIOP-Gateway] Error processing JSON-RPC payload: ${e.message}`);
                         res.writeHead(400);
                         res.end(JSON.stringify({
                             jsonrpc: "2.0",
@@ -108,7 +129,7 @@ export class LiopHybridGateway {
             // biome-ignore lint/suspicious/noExplicitAny: Standard gRPC stream data is Buffer
             const data = chunk;
             if (data)
-                console.error(`[LIOP-Gateway] Native gRPC Proxy passing ${data.length} bytes`);
+                log.info(`[LIOP-Gateway] Native gRPC Proxy passing ${data.length} bytes`);
         });
         stream.respond({ ":status": 200, "content-type": "application/grpc" });
         stream.end();
@@ -135,31 +156,32 @@ export class LiopHybridGateway {
             }
         });
     }
-    async listen(port, host = "::") {
+    async listen(port, host = "0.0.0.0") {
         if (this.meshNode) {
             await this.meshNode.start();
             // Announce all local tools to the DHT
             const tools = this.liopServer.listTools();
             for (const tool of tools) {
                 await this.meshNode.announceCapability(tool.name);
-                console.error(`[LIOP-Gateway] 📡 Announced local tool to Mesh: ${tool.name}`);
+                log.info(`[LIOP-Gateway] 📡 Announced local tool to Mesh: ${tool.name}`);
             }
         }
         return new Promise((resolve, reject) => {
             this.netServer.on("error", (err) => {
                 if (err.code === "EADDRINUSE") {
-                    console.error(`[LIOP-Gateway] FATAL: Port ${port} is already in use by another process.`);
+                    log.info(`[LIOP-Gateway] FATAL: Port ${port} is already in use by another process.`);
                 }
                 else {
-                    console.error(`[LIOP-Gateway] Binding Error: ${err.message}`);
+                    log.error(`[LIOP-Gateway] Binding Error: ${err.message}`);
                 }
                 reject(err);
             });
             this.netServer.listen(port, host, () => {
                 const addr = this.netServer.address();
                 const actualHost = typeof addr === "string" ? addr : addr?.address || host;
-                console.error(`[LIOP-Gateway] ✅ Transformer Mesh Gateway READY and listening on ${actualHost}:${port}`);
-                resolve();
+                const assignedPort = typeof addr === "string" ? port : addr?.port || port;
+                log.info(`[LIOP-Gateway] ✅ Transformer Mesh Gateway READY and listening on ${actualHost}:${assignedPort}`);
+                resolve(assignedPort);
             });
         });
     }
@@ -171,4 +193,7 @@ export class LiopHybridGateway {
         this.h2Server.close();
         this.h1Server.close();
     }
+    getRouter() {
+        return this.router;
+    }
 }

package/dist/gateway/router.d.ts

@@ -1,5 +1,7 @@
+import { LiopVerifier } from "../crypto/verifier.js";
 import type { MeshNode } from "../mesh/index.js";
 import type { LiopServer } from "../server/index.js";
+import type { McpRequest, McpResponse } from "../types.js";
 /**
  * LIOP MCP Router
  *
@@ -18,21 +20,35 @@ export declare class LiopMcpRouter {
     /** Guards against concurrent discovery storms */
     private currentDiscovery;
     /** Verifier for Tier-0 integrity checks */
-    private verifier;
+    verifier: LiopVerifier;
     /** Callback when new remote tools are discovered */
     onToolsChanged?: () => void;
+    /** Circuit-breaker state for peers that repeatedly fail manifest queries. */
+    private manifestFailureState;
+    private static readonly MANIFEST_FAILURE_BASE_COOLDOWN_MS;
+    private static readonly MANIFEST_FAILURE_MAX_COOLDOWN_MS;
+    private static readonly MANIFEST_SKIP_LOG_THROTTLE_MS;
     constructor(liopServer: LiopServer, meshNode?: MeshNode | null, defaultRpcPort?: number);
-    dispatch(request: {
-        method: string;
-        params?: any;
-        id?: any;
-    }): Promise<any>;
+    private shouldSkipManifestQuery;
+    private recordManifestQuerySuccess;
+    private recordManifestQueryFailure;
+    dispatch(request: McpRequest): Promise<McpResponse | null>;
+    /**
+     * MCP clients often send notifications/initialized then immediately tools/list.
+     * Start manifest discovery without blocking the notification handler.
+     */
+    private kickDiscoveryAfterInitialized;
     /**
      * Discovers and caches manifests from all remote LIOP providers in the mesh.
      * Uses Kademlia DHT to find "liop:manifest" providers, then opens
      * /liop/manifest/1.0.0 protocol streams to retrieve their full metadata.
      */
     refreshManifestCache(silent?: boolean): Promise<void>;
+    /**
+     * Returns the current manifest cache size for external telemetry.
+     * Used by the adaptive polling system to detect topology stabilization.
+     */
+    getCacheSize(): number;
     /**
      * Returns all remote tools discovered via the manifest protocol.
      */
@@ -42,10 +58,10 @@ export declare class LiopMcpRouter {
      */
     private getRemoteResources;
     /**
-     * Resolves the gRPC target (host:port) for a given tool name
-     * by searching the manifest cache. Returns null if not found.
+     * Resolves the gRPC target (host:port) AND the peerId for a given tool name
+     * by searching the manifest cache. Supports exact names and suffixed names.
      */
-    private resolveGrpcTarget;
+    private resolveManifestTarget;
     private transcodeMcpToLiop;
     private routeToRemoteProvider;
     private performTranscoding;