@cleocode/lafs-protocol 1.2.2 → 1.3.1

package/dist/src/discovery.js

@@ -1,204 +1,234 @@
 /**
  * LAFS Agent Discovery - Express/Fastify Middleware
- * Serves discovery document at /.well-known/lafs.json
+ * Serves A2A-compliant Agent Card at /.well-known/agent-card.json
+ * Maintains backward compatibility with legacy /.well-known/lafs.json
+ *
+ * A2A v1.0+ Compliant Implementation
+ * Reference: specs/external/agent-discovery.md
  */
 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
+import { buildLafsExtension } from './a2a/extensions.js';
 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);
-    }
-}
+// ============================================================================
+// Utility Functions
+// ============================================================================
 /**
  * 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
+ * Generate ETag from content
  */
 function generateETag(content) {
     return `"${createHash("sha256").update(content).digest("hex").slice(0, 32)}"`;
 }
 /**
- * Build discovery document from configuration
+ * Build A2A Agent Card from configuration
+ */
+function buildAgentCard(config, req) {
+    const schemaUrl = config.schemaUrl || "https://lafs.dev/schemas/v1/agent-card.schema.json";
+    // Handle legacy config migration
+    if (config.service && !config.agent) {
+        console.warn("[DEPRECATION] Using legacy 'service' config. Migrate to 'agent' format for A2A v1.0+ compliance.");
+        return {
+            $schema: schemaUrl,
+            name: config.service.name,
+            description: config.service.description || "LAFS-compliant agent",
+            version: config.lafsVersion || config.service.version || "1.0.0",
+            url: config.endpoints?.envelope
+                ? buildUrl(config.baseUrl, config.endpoints.envelope, req)
+                : buildUrl(config.baseUrl, "/", req),
+            capabilities: {
+                streaming: false,
+                pushNotifications: false,
+                extendedAgentCard: false,
+                extensions: []
+            },
+            defaultInputModes: ["application/json"],
+            defaultOutputModes: ["application/json"],
+            skills: (config.capabilities || []).map(cap => ({
+                id: cap.name.toLowerCase().replace(/\s+/g, "-"),
+                name: cap.name,
+                description: cap.description || `${cap.name} capability`,
+                tags: cap.operations || [],
+                examples: []
+            }))
+        };
+    }
+    // Standard A2A v1.0 Agent Card (agent is guaranteed present; legacy path returned above)
+    const agent = config.agent;
+    const card = {
+        $schema: schemaUrl,
+        ...agent,
+        url: agent.url || buildUrl(config.baseUrl, "/", req)
+    };
+    // Auto-include LAFS extension if configured
+    if (config.autoIncludeLafsExtension) {
+        const lafsOptions = typeof config.autoIncludeLafsExtension === 'object'
+            ? config.autoIncludeLafsExtension
+            : undefined;
+        const ext = buildLafsExtension(lafsOptions);
+        if (!card.capabilities.extensions) {
+            card.capabilities.extensions = [];
+        }
+        card.capabilities.extensions.push({
+            uri: ext.uri,
+            description: ext.description ?? 'LAFS envelope protocol for structured agent responses',
+            required: ext.required ?? false,
+            params: ext.params,
+        });
+    }
+    return card;
+}
+/**
+ * Build legacy discovery document for backward compatibility
+ * @deprecated Will be removed in v2.0.0
  */
-function buildDiscoveryDocument(config, req) {
+function buildLegacyDiscoveryDocument(config, req) {
     const schemaUrl = config.schemaUrl || "https://lafs.dev/schemas/v1/discovery.schema.json";
-    const lafsVersion = config.lafsVersion || "1.0.0";
+    const lafsVersion = config.lafsVersion || "1.3.1";
     return {
         $schema: schemaUrl,
         lafs_version: lafsVersion,
-        service: config.service,
-        capabilities: config.capabilities,
+        service: config.service || {
+            name: config.agent.name,
+            version: config.agent.version,
+            description: config.agent.description
+        },
+        capabilities: config.capabilities || config.agent.skills.map(skill => ({
+            name: skill.name,
+            version: config.agent.version,
+            description: skill.description,
+            operations: skill.tags,
+            optional: false
+        })),
         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)
+            envelope: buildUrl(config.baseUrl, config.endpoints?.envelope || config.agent.url, req),
+            context: config.endpoints?.context ? buildUrl(config.baseUrl, config.endpoints.context, req) : undefined,
+            discovery: config.endpoints?.discovery || buildUrl(config.baseUrl, "/.well-known/lafs.json", req)
         }
     };
 }
+// ============================================================================
+// Middleware
+// ============================================================================
 /**
- * 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
+ * Create Express middleware for serving A2A Agent Card
+ *
+ * Serves A2A-compliant Agent Card at /.well-known/agent-card.json
+ * Maintains backward compatibility with legacy /.well-known/lafs.json
  *
- * @param config - Discovery configuration
+ * @param config - Discovery configuration (A2A v1.0 format)
  * @param options - Middleware options
  * @returns Express RequestHandler
  *
  * @example
  * ```typescript
  * import express from "express";
- * import { discoveryMiddleware } from "./discovery.js";
+ * import { discoveryMiddleware } from "@cleocode/lafs-protocol/discovery";
  *
  * const app = express();
  *
  * app.use(discoveryMiddleware({
- *   service: {
- *     name: "my-lafs-service",
+ *   agent: {
+ *     name: "my-lafs-agent",
+ *     description: "A LAFS-compliant agent with A2A support",
  *     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"
+ *     url: "https://api.example.com",
+ *     capabilities: {
+ *       streaming: true,
+ *       pushNotifications: false,
+ *       extensions: []
+ *     },
+ *     defaultInputModes: ["application/json", "text/plain"],
+ *     defaultOutputModes: ["application/json"],
+ *     skills: [
+ *       {
+ *         id: "envelope-processor",
+ *         name: "Envelope Processor",
+ *         description: "Process LAFS envelopes",
+ *         tags: ["lafs", "envelope", "validation"],
+ *         examples: ["Validate this envelope", "Process envelope data"]
+ *       }
+ *     ]
  *   }
  * }));
  * ```
  */
 export function discoveryMiddleware(config, options = {}) {
-    const path = options.path || "/.well-known/lafs.json";
+    const path = options.path || "/.well-known/agent-card.json";
+    const legacyPath = options.legacyPath || "/.well-known/lafs.json";
+    // Disable legacy path by default when a custom path is set, unless explicitly enabled
+    const enableLegacyPath = options.enableLegacyPath ?? !options.path;
     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 (!config.agent && !config.service) {
+        throw new Error("Discovery config requires 'agent' (A2A v1.0) or 'service' (legacy) configuration");
     }
-    if (!Array.isArray(config.capabilities)) {
-        throw new Error("Discovery config requires capabilities array");
+    // Validate legacy service config fields
+    if (config.service) {
+        if (!config.service.name) {
+            throw new Error("Discovery config requires 'service.name'");
+        }
+        if (!config.service.version) {
+            throw new Error("Discovery config requires 'service.version'");
+        }
     }
-    if (!config.endpoints?.envelope) {
-        throw new Error("Discovery config requires endpoints.envelope");
+    // Validate legacy capabilities/endpoints when using service config
+    if (config.service && !config.agent) {
+        if (config.capabilities === undefined || config.capabilities === null) {
+            throw new Error("Discovery config requires 'capabilities' when using legacy 'service' config");
+        }
+        if (!config.endpoints?.envelope) {
+            throw new Error("Discovery config requires 'endpoints.envelope' when using legacy 'service' config");
+        }
+    }
+    // Cache serialized documents to ensure consistent ETags across GET/HEAD
+    let cachedPrimaryJson = null;
+    let cachedLegacyJson = null;
+    function getSerializedDoc(isLegacy, req) {
+        if (isLegacy) {
+            if (!cachedLegacyJson) {
+                cachedLegacyJson = JSON.stringify(buildLegacyDiscoveryDocument(config, req), null, 2);
+            }
+            return cachedLegacyJson;
+        }
+        if (!cachedPrimaryJson) {
+            cachedPrimaryJson = JSON.stringify(buildAgentCard(config, req), null, 2);
+        }
+        return cachedPrimaryJson;
     }
     return function discoveryHandler(req, res, next) {
-        // Only handle requests to the discovery path
-        if (req.path !== path) {
+        const isPrimaryPath = req.path === path;
+        const isLegacyPath = enableLegacyPath && req.path === legacyPath;
+        // Only handle requests to discovery paths
+        if (!isPrimaryPath && !isLegacyPath) {
             next();
             return;
         }
+        // Log deprecation warning for legacy path
+        if (isLegacyPath) {
+            console.warn(`[DEPRECATION] Accessing legacy discovery endpoint ${legacyPath}. ` +
+                `Migrate to ${path} for A2A v1.0+ compliance. Legacy support will be removed in v2.0.0.`);
+        }
         // Handle HEAD requests
         if (req.method === "HEAD") {
             if (!enableHead) {
@@ -208,23 +238,13 @@ export function discoveryMiddleware(config, options = {}) {
                 });
                 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;
+            const json = getSerializedDoc(isLegacyPath, req);
+            const etag = enableEtag ? generateETag(json) : undefined;
             res.set({
                 "Content-Type": "application/json",
                 "Cache-Control": `public, max-age=${cacheMaxAge}`,
                 ...(etag && { "ETag": etag }),
+                ...(isLegacyPath && { "Deprecation": "true", "Sunset": "Sat, 31 Dec 2025 23:59:59 GMT" }),
                 "Content-Length": Buffer.byteLength(json)
             });
             res.status(200).end();
@@ -239,23 +259,8 @@ export function discoveryMiddleware(config, options = {}) {
             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;
+            const json = getSerializedDoc(isLegacyPath, req);
+            const etag = enableEtag ? generateETag(json) : undefined;
             // Check If-None-Match for conditional request
             if (enableEtag && req.headers["if-none-match"] === etag) {
                 res.status(304).end();
@@ -270,6 +275,12 @@ export function discoveryMiddleware(config, options = {}) {
             if (etag) {
                 headers["ETag"] = etag;
             }
+            // Add deprecation headers for legacy path
+            if (isLegacyPath) {
+                headers["Deprecation"] = "true";
+                headers["Sunset"] = "Sat, 31 Dec 2025 23:59:59 GMT";
+                headers["Link"] = `<${buildUrl(config.baseUrl, path, req)}>; rel="successor-version"`;
+            }
             res.set(headers);
             res.status(200).send(json);
         }
@@ -279,18 +290,17 @@ export function discoveryMiddleware(config, options = {}) {
     };
 }
 /**
- * Fastify plugin for LAFS discovery (for Fastify users)
+ * Fastify plugin for A2A Agent Card discovery
  *
  * @param fastify - Fastify instance
  * @param options - Plugin options
  */
 export async function discoveryFastifyPlugin(fastify, options) {
-    const path = options.path || "/.well-known/lafs.json";
+    const path = options.path || "/.well-known/agent-card.json";
     const config = options.config;
     const cacheMaxAge = config.cacheMaxAge || 3600;
     const handler = async (request, reply) => {
-        const doc = buildDiscoveryDocument(config, request.raw);
-        validateDocument(doc);
+        const doc = buildAgentCard(config, request.raw);
         const json = JSON.stringify(doc);
         const etag = generateETag(json);
         reply.header("Content-Type", "application/json");
@@ -301,4 +311,32 @@ export async function discoveryFastifyPlugin(fastify, options) {
     // Note: Actual route registration depends on Fastify's API
     // This is a type-safe signature for the plugin
 }
+// ============================================================================
+// Breaking Changes Documentation
+// ============================================================================
+/**
+ * BREAKING CHANGES v1.2.3 → v2.0.0:
+ *
+ * 1. Discovery Endpoint Path
+ *    - OLD: /.well-known/lafs.json
+ *    - NEW: /.well-known/agent-card.json
+ *    - MIGRATION: Update client code to use new path
+ *    - BACKWARD COMPAT: Legacy path still works but logs deprecation warning
+ *
+ * 2. Discovery Document Format
+ *    - OLD: DiscoveryDocument interface (lafs_version, service, capabilities, endpoints)
+ *    - NEW: AgentCard interface (A2A v1.0 compliant)
+ *    - MIGRATION: Update config from 'service' to 'agent' format
+ *    - BACKWARD COMPAT: Legacy config format automatically converted with warning
+ *
+ * 3. Type Names
+ *    - Capability → AgentSkill (renamed to align with A2A spec)
+ *    - ServiceConfig → AgentCard (renamed)
+ *    - All old types marked as @deprecated
+ *
+ * 4. Removed in v2.0.0
+ *    - Legacy path support will be removed
+ *    - Old type definitions will be removed
+ *    - Automatic config migration will be removed
+ */
 export default discoveryMiddleware;

package/dist/src/index.d.ts

@@ -10,4 +10,6 @@ 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";
+export { LafsA2AResult, createLafsArtifact, createTextArtifact, createFileArtifact, isExtensionRequired, getExtensionParams, AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, LAFS_EXTENSION_URI, A2A_EXTENSIONS_HEADER, parseExtensionsHeader, negotiateExtensions, formatExtensionsHeader, buildLafsExtension, ExtensionSupportRequiredError, extensionNegotiationMiddleware, TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS, isValidTransition, isTerminalState, isInterruptedState, InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskManager, attachLafsEnvelope, } from "./a2a/index.js";
+export type { LafsA2AConfig, LafsSendMessageParams, LafsExtensionParams, ExtensionNegotiationResult, BuildLafsExtensionOptions, ExtensionNegotiationMiddlewareOptions, CreateTaskOptions, ListTasksOptions, ListTasksResult, } from "./a2a/index.js";
+export type { Task, TaskState, TaskStatus, Artifact, Part, Message, PushNotificationConfig, MessageSendConfiguration, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse, TextPart, DataPart, FilePart, } from "./a2a/index.js";

package/dist/src/index.js

@@ -12,4 +12,13 @@ export * from "./health/index.js";
 export * from "./shutdown/index.js";
 export * from "./circuit-breaker/index.js";
 // A2A Integration
-export * from "./a2a/index.js";
+// Explicitly re-export to avoid naming conflicts with discovery types
+// (AgentCard, AgentSkill, AgentCapabilities, AgentExtension).
+// For full A2A types, import from '@cleocode/lafs-protocol/a2a'.
+export { 
+// Bridge
+LafsA2AResult, createLafsArtifact, createTextArtifact, createFileArtifact, isExtensionRequired, getExtensionParams, 
+// Extensions (T098)
+LAFS_EXTENSION_URI, A2A_EXTENSIONS_HEADER, parseExtensionsHeader, negotiateExtensions, formatExtensionsHeader, buildLafsExtension, ExtensionSupportRequiredError, extensionNegotiationMiddleware, 
+// Task Lifecycle (T099)
+TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS, isValidTransition, isTerminalState, isInterruptedState, InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskManager, attachLafsEnvelope, } from "./a2a/index.js";

package/lafs.md

@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.2.2 | **Status:** Production Ready
+> **Version:** 1.3.1 | **Status:** Production Ready
 
 ## 1. Scope
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",
@@ -10,6 +10,18 @@
     ".": {
       "import": "./dist/src/index.js",
       "types": "./dist/src/index.d.ts"
+    },
+    "./discovery": {
+      "import": "./dist/src/discovery.js",
+      "types": "./dist/src/discovery.d.ts"
+    },
+    "./a2a": {
+      "import": "./dist/src/a2a/index.js",
+      "types": "./dist/src/a2a/index.d.ts"
+    },
+    "./a2a/bindings": {
+      "import": "./dist/src/a2a/bindings/index.js",
+      "types": "./dist/src/a2a/bindings/index.d.ts"
     }
   },
   "files": [
@@ -48,6 +60,7 @@
     "schema",
     "conformance"
   ],
+  "author": "CLEO Code <hello@cleo.co> (https://cleo.co)",
   "license": "MIT",
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",