@cleocode/lafs-protocol 0.5.0 → 1.1.0

package/dist/src/health/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * LAFS Health Check Module
+ *
+ * Provides health check endpoints for monitoring and orchestration
+ */
+export interface HealthCheckConfig {
+    path?: string;
+    checks?: HealthCheckFunction[];
+}
+export type HealthCheckFunction = () => Promise<HealthCheckResult> | HealthCheckResult;
+export interface HealthCheckResult {
+    name: string;
+    status: 'ok' | 'warning' | 'error';
+    message?: string;
+    duration?: number;
+}
+export interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    timestamp: string;
+    version: string;
+    uptime: number;
+    checks: HealthCheckResult[];
+}
+/**
+ * Health check middleware for Express applications
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { healthCheck } from '@cleocode/lafs-protocol/health';
+ *
+ * const app = express();
+ *
+ * // Basic health check
+ * app.use('/health', healthCheck());
+ *
+ * // Custom health checks
+ * app.use('/health', healthCheck({
+ *   checks: [
+ *     async () => ({
+ *       name: 'database',
+ *       status: await checkDatabase() ? 'ok' : 'error'
+ *     })
+ *   ]
+ * }));
+ * ```
+ */
+export declare function healthCheck(config?: HealthCheckConfig): (req: any, res: any) => Promise<void>;
+/**
+ * Create a database health check
+ *
+ * @example
+ * ```typescript
+ * const dbCheck = createDatabaseHealthCheck({
+ *   checkConnection: async () => await db.ping()
+ * });
+ *
+ * app.use('/health', healthCheck({
+ *   checks: [dbCheck]
+ * }));
+ * ```
+ */
+export declare function createDatabaseHealthCheck(config: {
+    checkConnection: () => Promise<boolean>;
+    name?: string;
+}): HealthCheckFunction;
+/**
+ * Create an external service health check
+ *
+ * @example
+ * ```typescript
+ * const apiCheck = createExternalServiceHealthCheck({
+ *   name: 'payment-api',
+ *   url: 'https://api.payment.com/health',
+ *   timeout: 5000
+ * });
+ * ```
+ */
+export declare function createExternalServiceHealthCheck(config: {
+    name: string;
+    url: string;
+    timeout?: number;
+}): HealthCheckFunction;
+/**
+ * Liveness probe - basic check that service is running
+ *
+ * @example
+ * ```typescript
+ * app.get('/health/live', livenessProbe());
+ * ```
+ */
+export declare function livenessProbe(): (req: any, res: any) => void;
+/**
+ * Readiness probe - check that service is ready to accept traffic
+ *
+ * @example
+ * ```typescript
+ * app.get('/health/ready', readinessProbe({
+ *   checks: [dbCheck, cacheCheck]
+ * }));
+ * ```
+ */
+export declare function readinessProbe(config?: {
+    checks?: HealthCheckFunction[];
+}): (req: any, res: any) => Promise<void>;

package/dist/src/health/index.js

@@ -0,0 +1,211 @@
+/**
+ * LAFS Health Check Module
+ *
+ * Provides health check endpoints for monitoring and orchestration
+ */
+/**
+ * Health check middleware for Express applications
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { healthCheck } from '@cleocode/lafs-protocol/health';
+ *
+ * const app = express();
+ *
+ * // Basic health check
+ * app.use('/health', healthCheck());
+ *
+ * // Custom health checks
+ * app.use('/health', healthCheck({
+ *   checks: [
+ *     async () => ({
+ *       name: 'database',
+ *       status: await checkDatabase() ? 'ok' : 'error'
+ *     })
+ *   ]
+ * }));
+ * ```
+ */
+export function healthCheck(config = {}) {
+    const { path = '/health', checks = [] } = config;
+    const startTime = Date.now();
+    return async (req, res) => {
+        const timestamp = new Date().toISOString();
+        const checkResults = [];
+        // Run all health checks
+        for (const check of checks) {
+            const start = Date.now();
+            try {
+                const result = await check();
+                result.duration = Date.now() - start;
+                checkResults.push(result);
+            }
+            catch (error) {
+                checkResults.push({
+                    name: 'unknown',
+                    status: 'error',
+                    message: error instanceof Error ? error.message : 'Check failed',
+                    duration: Date.now() - start
+                });
+            }
+        }
+        // Add default checks
+        checkResults.push({
+            name: 'envelopeValidation',
+            status: 'ok'
+        });
+        checkResults.push({
+            name: 'tokenBudgets',
+            status: 'ok'
+        });
+        // Determine overall status
+        const hasErrors = checkResults.some(c => c.status === 'error');
+        const hasWarnings = checkResults.some(c => c.status === 'warning');
+        const status = hasErrors
+            ? 'unhealthy'
+            : hasWarnings
+                ? 'degraded'
+                : 'healthy';
+        const health = {
+            status,
+            timestamp,
+            version: process.env.npm_package_version || '1.1.0',
+            uptime: Math.floor((Date.now() - startTime) / 1000),
+            checks: checkResults
+        };
+        const statusCode = status === 'healthy' ? 200 : status === 'degraded' ? 200 : 503;
+        res.status(statusCode).json(health);
+    };
+}
+/**
+ * Create a database health check
+ *
+ * @example
+ * ```typescript
+ * const dbCheck = createDatabaseHealthCheck({
+ *   checkConnection: async () => await db.ping()
+ * });
+ *
+ * app.use('/health', healthCheck({
+ *   checks: [dbCheck]
+ * }));
+ * ```
+ */
+export function createDatabaseHealthCheck(config) {
+    return async () => {
+        try {
+            const isConnected = await config.checkConnection();
+            return {
+                name: config.name || 'database',
+                status: isConnected ? 'ok' : 'error',
+                message: isConnected ? 'Connected' : 'Connection failed'
+            };
+        }
+        catch (error) {
+            return {
+                name: config.name || 'database',
+                status: 'error',
+                message: error instanceof Error ? error.message : 'Database check failed'
+            };
+        }
+    };
+}
+/**
+ * Create an external service health check
+ *
+ * @example
+ * ```typescript
+ * const apiCheck = createExternalServiceHealthCheck({
+ *   name: 'payment-api',
+ *   url: 'https://api.payment.com/health',
+ *   timeout: 5000
+ * });
+ * ```
+ */
+export function createExternalServiceHealthCheck(config) {
+    return async () => {
+        const start = Date.now();
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), config.timeout || 5000);
+            const response = await fetch(config.url, {
+                signal: controller.signal
+            });
+            clearTimeout(timeout);
+            return {
+                name: config.name,
+                status: response.ok ? 'ok' : 'error',
+                message: response.ok ? 'Service healthy' : `HTTP ${response.status}`,
+                duration: Date.now() - start
+            };
+        }
+        catch (error) {
+            return {
+                name: config.name,
+                status: 'error',
+                message: error instanceof Error ? error.message : 'Service unreachable',
+                duration: Date.now() - start
+            };
+        }
+    };
+}
+/**
+ * Liveness probe - basic check that service is running
+ *
+ * @example
+ * ```typescript
+ * app.get('/health/live', livenessProbe());
+ * ```
+ */
+export function livenessProbe() {
+    return (req, res) => {
+        res.status(200).json({
+            status: 'alive',
+            timestamp: new Date().toISOString()
+        });
+    };
+}
+/**
+ * Readiness probe - check that service is ready to accept traffic
+ *
+ * @example
+ * ```typescript
+ * app.get('/health/ready', readinessProbe({
+ *   checks: [dbCheck, cacheCheck]
+ * }));
+ * ```
+ */
+export function readinessProbe(config = {}) {
+    return async (req, res) => {
+        const checkResults = [];
+        if (config.checks) {
+            for (const check of config.checks) {
+                try {
+                    const result = await check();
+                    checkResults.push(result);
+                }
+                catch (error) {
+                    checkResults.push({
+                        name: 'unknown',
+                        status: 'error',
+                        message: error instanceof Error ? error.message : 'Check failed'
+                    });
+                }
+            }
+        }
+        const hasErrors = checkResults.some(c => c.status === 'error');
+        if (hasErrors) {
+            res.status(503).json({
+                status: 'not ready',
+                checks: checkResults
+            });
+        }
+        else {
+            res.status(200).json({
+                status: 'ready',
+                checks: checkResults
+            });
+        }
+    };
+}

package/dist/src/index.d.ts

@@ -3,3 +3,11 @@ export * from "./errorRegistry.js";
 export * from "./validateEnvelope.js";
 export * from "./flagSemantics.js";
 export * from "./conformance.js";
+export * from "./tokenEstimator.js";
+export * from "./budgetEnforcement.js";
+export * from "./mcpAdapter.js";
+export * from "./discovery.js";
+export * from "./health/index.js";
+export * from "./shutdown/index.js";
+export * from "./circuit-breaker/index.js";
+export * from "./a2a/index.js";

package/dist/src/index.js

@@ -3,3 +3,13 @@ export * from "./errorRegistry.js";
 export * from "./validateEnvelope.js";
 export * from "./flagSemantics.js";
 export * from "./conformance.js";
+export * from "./tokenEstimator.js";
+export * from "./budgetEnforcement.js";
+export * from "./mcpAdapter.js";
+export * from "./discovery.js";
+// Operations & Reliability
+export * from "./health/index.js";
+export * from "./shutdown/index.js";
+export * from "./circuit-breaker/index.js";
+// A2A Integration
+export * from "./a2a/index.js";

package/dist/src/mcpAdapter.d.ts

@@ -0,0 +1,28 @@
+import type { CallToolResult, TextContent } from "@modelcontextprotocol/sdk/types.js";
+import type { LAFSEnvelope, LAFSError } from "./types.js";
+/**
+ * Wrap MCP tool result in LAFS envelope
+ *
+ * @param mcpResult - The raw MCP CallToolResult
+ * @param operation - The operation name (tool name)
+ * @param budget - Optional token budget for response
+ * @returns LAFS-compliant envelope
+ */
+export declare function wrapMCPResult(mcpResult: CallToolResult, operation: string, budget?: number): LAFSEnvelope;
+/**
+ * Create a LAFS error envelope for MCP adapter errors
+ *
+ * @param message - Error message
+ * @param operation - The operation being performed
+ * @param category - Error category
+ * @returns LAFS error envelope
+ */
+export declare function createAdapterErrorEnvelope(message: string, operation: string, category?: LAFSError["category"]): LAFSEnvelope;
+/**
+ * Type guard to check if content is TextContent
+ */
+export declare function isTextContent(content: unknown): content is TextContent;
+/**
+ * Parse MCP text content as JSON if possible
+ */
+export declare function parseMCPTextContent(content: TextContent): unknown;

package/dist/src/mcpAdapter.js

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Extract result from MCP content array
+ * Attempts to parse JSON content, falls back to text representation
+ */
+function extractResultFromContent(content) {
+    if (!content || content.length === 0) {
+        return null;
+    }
+    // Combine all text content
+    const textParts = [];
+    const otherContent = [];
+    for (const item of content) {
+        if (item.type === "text" && item.text) {
+            textParts.push(item.text);
+        }
+        else {
+            otherContent.push(item);
+        }
+    }
+    // Try to parse as JSON if single text item looks like JSON
+    if (textParts.length === 1) {
+        const text = textParts[0]?.trim() ?? "";
+        if (text.startsWith("{") || text.startsWith("[")) {
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed === "object" && parsed !== null) {
+                    return parsed;
+                }
+            }
+            catch {
+                // Not valid JSON, treat as text
+            }
+        }
+    }
+    // Combine into result object
+    const result = {};
+    if (textParts.length > 0) {
+        result.text = textParts.length === 1 ? textParts[0] : textParts.join("\n");
+    }
+    if (otherContent.length > 0) {
+        result.content = otherContent;
+    }
+    return result;
+}
+/**
+ * Estimate token count from content
+ * Rough estimation: ~4 characters per token
+ */
+function estimateTokens(content) {
+    if (!content)
+        return 0;
+    const jsonString = JSON.stringify(content);
+    return Math.ceil(jsonString.length / 4);
+}
+/**
+ * Truncate content to fit within budget
+ */
+function truncateToBudget(content, budget) {
+    if (!content)
+        return { result: null, truncated: false, originalEstimate: 0 };
+    const originalEstimate = estimateTokens(content);
+    if (originalEstimate <= budget) {
+        return { result: content, truncated: false, originalEstimate };
+    }
+    // Calculate truncation ratio
+    const ratio = budget / originalEstimate;
+    const jsonString = JSON.stringify(content);
+    const targetLength = Math.floor(jsonString.length * ratio);
+    // Truncate the string and try to make it valid JSON
+    let truncated = jsonString.slice(0, targetLength);
+    // Close any open structures
+    const openBraces = (truncated.match(/\{/g) || []).length - (truncated.match(/\}/g) || []).length;
+    const openBrackets = (truncated.match(/\[/g) || []).length - (truncated.match(/\]/g) || []).length;
+    truncated += "}".repeat(Math.max(0, openBraces));
+    truncated += "]".repeat(Math.max(0, openBrackets));
+    try {
+        const parsed = JSON.parse(truncated);
+        // Add truncation notice
+        if (typeof parsed === "object" && parsed !== null) {
+            parsed["_truncated"] = true;
+            parsed["_originalTokens"] = originalEstimate;
+            parsed["_budget"] = budget;
+        }
+        return { result: parsed, truncated: true, originalEstimate };
+    }
+    catch {
+        // If parsing fails, return minimal result
+        return {
+            result: {
+                _truncated: true,
+                _error: "Content truncated due to budget constraints",
+                _originalTokens: originalEstimate,
+                _budget: budget,
+            },
+            truncated: true,
+            originalEstimate,
+        };
+    }
+}
+/**
+ * Convert MCP error to LAFS error format
+ */
+function convertMCPErrorToLAFS(mcpResult, operation) {
+    const content = mcpResult.content;
+    const errorText = content
+        .filter((item) => item.type === "text" && typeof item.text === "string")
+        .map((item) => item.text)
+        .join("\n");
+    // Determine error category based on error text
+    let category = "INTERNAL";
+    let code = "E_MCP_INTERNAL_ERROR";
+    let retryable = false;
+    let retryAfterMs = null;
+    const errorLower = errorText.toLowerCase();
+    if (errorLower.includes("not found") || errorLower.includes("doesn't exist") || errorLower.includes("does not exist")) {
+        category = "NOT_FOUND";
+        code = "E_MCP_NOT_FOUND";
+    }
+    else if (errorLower.includes("rate limit") || errorLower.includes("too many requests")) {
+        category = "RATE_LIMIT";
+        code = "E_MCP_RATE_LIMIT";
+        retryable = true;
+        retryAfterMs = 60000; // 1 minute default
+    }
+    else if (errorLower.includes("auth") || errorLower.includes("unauthorized") || errorLower.includes("forbidden")) {
+        category = "AUTH";
+        code = "E_MCP_AUTH_ERROR";
+    }
+    else if (errorLower.includes("permission") || errorLower.includes("access denied")) {
+        category = "PERMISSION";
+        code = "E_MCP_PERMISSION_DENIED";
+    }
+    else if (errorLower.includes("validation") || errorLower.includes("invalid")) {
+        category = "VALIDATION";
+        code = "E_MCP_VALIDATION_ERROR";
+    }
+    else if (errorLower.includes("timeout") || errorLower.includes("transient")) {
+        category = "TRANSIENT";
+        code = "E_MCP_TRANSIENT_ERROR";
+        retryable = true;
+        retryAfterMs = 5000; // 5 seconds
+    }
+    return {
+        code,
+        message: errorText || "MCP tool execution failed",
+        category,
+        retryable,
+        retryAfterMs,
+        details: {
+            operation,
+            mcpError: true,
+            contentTypes: content.map((c) => c.type),
+        },
+    };
+}
+/**
+ * Wrap MCP tool result in LAFS envelope
+ *
+ * @param mcpResult - The raw MCP CallToolResult
+ * @param operation - The operation name (tool name)
+ * @param budget - Optional token budget for response
+ * @returns LAFS-compliant envelope
+ */
+export function wrapMCPResult(mcpResult, operation, budget) {
+    const requestId = randomUUID();
+    const timestamp = new Date().toISOString();
+    // Build base meta
+    const meta = {
+        specVersion: "1.0.0",
+        schemaVersion: "1.0.0",
+        timestamp,
+        operation,
+        requestId,
+        transport: "sdk",
+        strict: true,
+        mvi: "standard",
+        contextVersion: 1,
+    };
+    // Handle MCP error
+    if (mcpResult.isError) {
+        const error = convertMCPErrorToLAFS(mcpResult, operation);
+        return {
+            $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+            _meta: meta,
+            success: false,
+            result: null,
+            error,
+        };
+    }
+    // Extract result from MCP content
+    let result = extractResultFromContent(mcpResult.content);
+    let truncated = false;
+    let originalEstimate = 0;
+    let extensions;
+    // Apply budget enforcement if specified
+    if (budget !== undefined && budget > 0) {
+        const budgetResult = truncateToBudget(result, budget);
+        result = budgetResult.result;
+        truncated = budgetResult.truncated;
+        originalEstimate = budgetResult.originalEstimate;
+        // Put token estimate in extensions to comply with strict schema
+        extensions = {
+            "x-mcp-token-estimate": {
+                estimated: truncated ? budget : originalEstimate,
+                truncated,
+                originalEstimate: truncated ? originalEstimate : undefined,
+            },
+        };
+    }
+    return {
+        $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+        _meta: meta,
+        success: true,
+        result,
+        error: null,
+        _extensions: extensions,
+    };
+}
+/**
+ * Create a LAFS error envelope for MCP adapter errors
+ *
+ * @param message - Error message
+ * @param operation - The operation being performed
+ * @param category - Error category
+ * @returns LAFS error envelope
+ */
+export function createAdapterErrorEnvelope(message, operation, category = "INTERNAL") {
+    const requestId = randomUUID();
+    const timestamp = new Date().toISOString();
+    const error = {
+        code: "E_MCP_ADAPTER_ERROR",
+        message,
+        category,
+        retryable: category === "TRANSIENT" || category === "RATE_LIMIT",
+        retryAfterMs: category === "RATE_LIMIT" ? 60000 : category === "TRANSIENT" ? 5000 : null,
+        details: {
+            operation,
+            adapterError: true,
+        },
+    };
+    return {
+        $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+        _meta: {
+            specVersion: "1.0.0",
+            schemaVersion: "1.0.0",
+            timestamp,
+            operation,
+            requestId,
+            transport: "sdk",
+            strict: true,
+            mvi: "standard",
+            contextVersion: 1,
+        },
+        success: false,
+        result: null,
+        error,
+    };
+}
+/**
+ * Type guard to check if content is TextContent
+ */
+export function isTextContent(content) {
+    return (typeof content === "object" &&
+        content !== null &&
+        "type" in content &&
+        content.type === "text" &&
+        "text" in content &&
+        typeof content.text === "string");
+}
+/**
+ * Parse MCP text content as JSON if possible
+ */
+export function parseMCPTextContent(content) {
+    try {
+        return JSON.parse(content.text);
+    }
+    catch {
+        return content.text;
+    }
+}