@cleocode/lafs-protocol 0.5.0 → 1.0.0

package/dist/src/discovery.js

@@ -0,0 +1,304 @@
+/**
+ * LAFS Agent Discovery - Express/Fastify Middleware
+ * Serves discovery document at /.well-known/lafs.json
+ */
+import { createRequire } from "node:module";
+import { createHash } from "crypto";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Handle ESM/CommonJS interop for AJV
+const require = createRequire(import.meta.url);
+const AjvModule = require("ajv");
+const AddFormatsModule = require("ajv-formats");
+const AjvCtor = (typeof AjvModule === "function" ? AjvModule : AjvModule.default);
+const addFormats = (typeof AddFormatsModule === "function" ? AddFormatsModule : AddFormatsModule.default);
+let ajvInstance = null;
+let validateDiscovery = null;
+/**
+ * Initialize AJV validator for discovery documents
+ */
+function initValidator() {
+    if (ajvInstance && validateDiscovery)
+        return;
+    ajvInstance = new AjvCtor({ strict: true, allErrors: true });
+    addFormats(ajvInstance);
+    try {
+        // Try to load schema from schemas directory
+        const schemaPath = join(__dirname, "..", "..", "schemas", "v1", "discovery.schema.json");
+        const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+        validateDiscovery = ajvInstance.compile(schema);
+    }
+    catch (e) {
+        // Fallback to inline schema if file not found
+        const fallbackSchema = {
+            $schema: "http://json-schema.org/draft-07/schema#",
+            type: "object",
+            required: ["$schema", "lafs_version", "service", "capabilities", "endpoints"],
+            properties: {
+                $schema: { type: "string", format: "uri" },
+                lafs_version: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+$" },
+                service: {
+                    type: "object",
+                    required: ["name", "version"],
+                    properties: {
+                        name: { type: "string", minLength: 1 },
+                        version: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+$" },
+                        description: { type: "string" }
+                    }
+                },
+                capabilities: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        required: ["name", "version", "operations"],
+                        properties: {
+                            name: { type: "string", minLength: 1 },
+                            version: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+$" },
+                            description: { type: "string" },
+                            operations: { type: "array", items: { type: "string" } },
+                            optional: { type: "boolean" }
+                        }
+                    }
+                },
+                endpoints: {
+                    type: "object",
+                    required: ["envelope", "discovery"],
+                    properties: {
+                        envelope: { type: "string", minLength: 1 },
+                        context: { type: "string", minLength: 1 },
+                        discovery: { type: "string", minLength: 1 }
+                    }
+                }
+            }
+        };
+        validateDiscovery = ajvInstance.compile(fallbackSchema);
+    }
+}
+/**
+ * Build absolute URL from base and path
+ */
+function buildUrl(base, path, req) {
+    // If path is already absolute, return it
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+        return path;
+    }
+    // If base is provided, use it
+    if (base) {
+        const separator = base.endsWith("/") || path.startsWith("/") ? "" : "/";
+        return `${base}${separator}${path}`;
+    }
+    // Otherwise try to construct from request
+    if (req) {
+        const protocol = req.headers["x-forwarded-proto"] || req.protocol || "http";
+        const host = req.headers.host || "localhost";
+        const separator = path.startsWith("/") ? "" : "/";
+        return `${protocol}://${host}${separator}${path}`;
+    }
+    // Fallback to relative path
+    return path.startsWith("/") ? path : `/${path}`;
+}
+/**
+ * Generate ETag from document content
+ */
+function generateETag(content) {
+    return `"${createHash("sha256").update(content).digest("hex").slice(0, 32)}"`;
+}
+/**
+ * Build discovery document from configuration
+ */
+function buildDiscoveryDocument(config, req) {
+    const schemaUrl = config.schemaUrl || "https://lafs.dev/schemas/v1/discovery.schema.json";
+    const lafsVersion = config.lafsVersion || "1.0.0";
+    return {
+        $schema: schemaUrl,
+        lafs_version: lafsVersion,
+        service: config.service,
+        capabilities: config.capabilities,
+        endpoints: {
+            envelope: buildUrl(config.baseUrl, config.endpoints.envelope, req),
+            context: config.endpoints.context
+                ? buildUrl(config.baseUrl, config.endpoints.context, req)
+                : undefined,
+            discovery: config.endpoints.discovery
+                ? buildUrl(config.baseUrl, config.endpoints.discovery, req)
+                : buildUrl(config.baseUrl, "/.well-known/lafs.json", req)
+        }
+    };
+}
+/**
+ * Validate discovery document against schema
+ */
+function validateDocument(doc) {
+    initValidator();
+    if (!validateDiscovery) {
+        throw new Error("Discovery document validator not initialized");
+    }
+    const valid = validateDiscovery(doc);
+    if (!valid) {
+        const errors = validateDiscovery.errors;
+        const errorMessages = errors?.map((e) => `${e.instancePath || "root"}: ${e.message}`).join("; ");
+        throw new Error(`Discovery document validation failed: ${errorMessages}`);
+    }
+}
+/**
+ * Create Express middleware for serving LAFS discovery document
+ *
+ * @param config - Discovery configuration
+ * @param options - Middleware options
+ * @returns Express RequestHandler
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { discoveryMiddleware } from "./discovery.js";
+ *
+ * const app = express();
+ *
+ * app.use(discoveryMiddleware({
+ *   service: {
+ *     name: "my-lafs-service",
+ *     version: "1.0.0",
+ *     description: "A LAFS-compliant API service"
+ *   },
+ *   capabilities: [
+ *     {
+ *       name: "envelope-processor",
+ *       version: "1.0.0",
+ *       operations: ["process", "validate"],
+ *       description: "Process LAFS envelopes"
+ *     }
+ *   ],
+ *   endpoints: {
+ *     envelope: "/api/v1/envelope",
+ *     context: "/api/v1/context"
+ *   }
+ * }));
+ * ```
+ */
+export function discoveryMiddleware(config, options = {}) {
+    const path = options.path || "/.well-known/lafs.json";
+    const enableHead = options.enableHead !== false;
+    const enableEtag = options.enableEtag !== false;
+    const cacheMaxAge = config.cacheMaxAge || 3600;
+    // Validate configuration
+    if (!config.service?.name || !config.service?.version) {
+        throw new Error("Discovery config requires service.name and service.version");
+    }
+    if (!Array.isArray(config.capabilities)) {
+        throw new Error("Discovery config requires capabilities array");
+    }
+    if (!config.endpoints?.envelope) {
+        throw new Error("Discovery config requires endpoints.envelope");
+    }
+    return function discoveryHandler(req, res, next) {
+        // Only handle requests to the discovery path
+        if (req.path !== path) {
+            next();
+            return;
+        }
+        // Handle HEAD requests
+        if (req.method === "HEAD") {
+            if (!enableHead) {
+                res.status(405).json({
+                    error: "Method Not Allowed",
+                    message: "HEAD requests are disabled for this endpoint"
+                });
+                return;
+            }
+            // For HEAD, we still need to build the document to get the ETag
+            const doc = buildDiscoveryDocument(config, req);
+            const json = JSON.stringify(doc);
+            // Generate stable ETag from config hash (not request-dependent document)
+            const configHash = generateETag(JSON.stringify({
+                schemaUrl: config.schemaUrl,
+                lafsVersion: config.lafsVersion,
+                service: config.service,
+                capabilities: config.capabilities,
+                endpoints: config.endpoints,
+                cacheMaxAge: config.cacheMaxAge
+            }));
+            const etag = enableEtag ? configHash : undefined;
+            res.set({
+                "Content-Type": "application/json",
+                "Cache-Control": `public, max-age=${cacheMaxAge}`,
+                ...(etag && { "ETag": etag }),
+                "Content-Length": Buffer.byteLength(json)
+            });
+            res.status(200).end();
+            return;
+        }
+        // Only handle GET requests
+        if (req.method !== "GET") {
+            res.status(405).json({
+                error: "Method Not Allowed",
+                message: `Method ${req.method} not allowed. Use GET or HEAD.`
+            });
+            return;
+        }
+        try {
+            // Build discovery document
+            const doc = buildDiscoveryDocument(config, req);
+            // Validate against schema
+            validateDocument(doc);
+            // Serialize document
+            const json = JSON.stringify(doc);
+            // Generate ETag from config hash (stable) rather than request-dependent document
+            // This ensures ETag is consistent across requests even when URLs are constructed from request
+            const configHash = generateETag(JSON.stringify({
+                schemaUrl: config.schemaUrl,
+                lafsVersion: config.lafsVersion,
+                service: config.service,
+                capabilities: config.capabilities,
+                endpoints: config.endpoints,
+                cacheMaxAge: config.cacheMaxAge
+            }));
+            const etag = enableEtag ? configHash : undefined;
+            // Check If-None-Match for conditional request
+            if (enableEtag && req.headers["if-none-match"] === etag) {
+                res.status(304).end();
+                return;
+            }
+            // Set response headers
+            const headers = {
+                "Content-Type": "application/json",
+                "Cache-Control": `public, max-age=${cacheMaxAge}`,
+                ...config.headers
+            };
+            if (etag) {
+                headers["ETag"] = etag;
+            }
+            res.set(headers);
+            res.status(200).send(json);
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/**
+ * Fastify plugin for LAFS discovery (for Fastify users)
+ *
+ * @param fastify - Fastify instance
+ * @param options - Plugin options
+ */
+export async function discoveryFastifyPlugin(fastify, options) {
+    const path = options.path || "/.well-known/lafs.json";
+    const config = options.config;
+    const cacheMaxAge = config.cacheMaxAge || 3600;
+    const handler = async (request, reply) => {
+        const doc = buildDiscoveryDocument(config, request.raw);
+        validateDocument(doc);
+        const json = JSON.stringify(doc);
+        const etag = generateETag(json);
+        reply.header("Content-Type", "application/json");
+        reply.header("Cache-Control", `public, max-age=${cacheMaxAge}`);
+        reply.header("ETag", etag);
+        return doc;
+    };
+    // Note: Actual route registration depends on Fastify's API
+    // This is a type-safe signature for the plugin
+}
+export default discoveryMiddleware;

package/dist/src/index.d.ts

@@ -3,3 +3,7 @@ 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";

package/dist/src/index.js

@@ -3,3 +3,7 @@ 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";

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