@cleocode/lafs-protocol 0.5.0 → 1.1.0

package/README.md

@@ -4,7 +4,10 @@
 
 LAFS defines a standard envelope format for structured responses from LLM-powered agents and tools. It complements transport protocols like [MCP](https://modelcontextprotocol.io/) and [A2A](https://github.com/google/A2A) by standardizing what comes back — not how it gets there.
 
-**Current version:** 0.5.0 | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 1.0.0 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+
+[![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs-protocol/)
+[![npm](https://img.shields.io/npm/v/@cleocode/lafs-protocol)](https://www.npmjs.com/package/@cleocode/lafs-protocol)
 
 ## What LAFS provides
 
@@ -17,7 +20,7 @@ LAFS defines a standard envelope format for structured responses from LLM-powere
 | **Tooling** | `src/` | TypeScript validation, conformance runner, CLI diagnostic tool |
 | **Tests** | `tests/` | 31 tests covering envelope, pagination, strict mode, error handling |
 | **Fixtures** | `fixtures/` | 14 JSON fixtures (valid + invalid) for conformance testing |
-| **Docs** | `docs/` | Positioning, vision, conformance tiers, deprecation policy |
+| **Docs** | `docs/` | [GitBook documentation](https://codluv.gitbook.io/lafs-protocol/) with guides, SDK reference, and specs |
 
 ## Install
 
@@ -64,7 +67,7 @@ npm run typecheck
 {
   "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
   "_meta": {
-    "specVersion": "0.5.0",
+    "specVersion": "1.0.0",
     "schemaVersion": "1.0.0",
     "timestamp": "2026-02-13T00:00:00Z",
     "operation": "example.list",
@@ -139,6 +142,7 @@ CONTRIBUTING.md                  # Contributor guidelines, RFC process
 
 | Version | Phase | Description |
 |---------|-------|-------------|
+| **v1.0.0** | **3** | **Production release: Token budgets, agent discovery, MCP integration, complete SDKs** |
 | v0.5.0 | 2B | Conditional pagination, MVI field selection/expansion, context ledger schema |
 | v0.4.0 | 2A | Optional page/error, extensions, strict/lenient mode, warnings |
 | v0.3.0 | 1 | Strategic positioning, vision alignment, adoption tiers |

package/dist/examples/discovery-server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * LAFS Discovery Example Server
+ *
+ * Run with: npx tsx examples/discovery-server.ts
+ * Or: npm run build && node dist/examples/discovery-server.js
+ */
+declare const app: import("express-serve-static-core").Express;
+export default app;

package/dist/examples/discovery-server.js

@@ -0,0 +1,216 @@
+/**
+ * LAFS Discovery Example Server
+ *
+ * Run with: npx tsx examples/discovery-server.ts
+ * Or: npm run build && node dist/examples/discovery-server.js
+ */
+import express from "express";
+import { discoveryMiddleware } from "../src/discovery.js";
+const app = express();
+const PORT = process.env.PORT || 3000;
+/**
+ * LAFS-compliant envelope endpoint handler
+ * Demonstrates proper LAFS envelope processing
+ */
+app.post("/api/v1/envelope", express.json(), (req, res) => {
+    const envelope = req.body;
+    // Validate basic envelope structure
+    if (!envelope._meta) {
+        return res.status(400).json({
+            success: false,
+            error: {
+                code: "INVALID_ENVELOPE",
+                message: "Missing _meta field",
+                category: "VALIDATION",
+                retryable: false,
+                retryAfterMs: null,
+                details: { missing: ["_meta"] }
+            },
+            result: null
+        });
+    }
+    // Process the request (simplified example)
+    const operation = envelope._meta.operation;
+    // Echo back with success
+    res.json({
+        $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+        _meta: {
+            specVersion: envelope._meta.specVersion || "1.0.0",
+            schemaVersion: envelope._meta.schemaVersion || "1.0.0",
+            timestamp: new Date().toISOString(),
+            operation: `${operation}:response`,
+            requestId: envelope._meta.requestId || crypto.randomUUID(),
+            transport: "http",
+            strict: envelope._meta.strict ?? true,
+            mvi: envelope._meta.mvi || "standard",
+            contextVersion: (envelope._meta.contextVersion || 0) + 1
+        },
+        success: true,
+        result: {
+            received: true,
+            operation: operation,
+            data: envelope.payload || null
+        },
+        error: null
+    });
+});
+/**
+ * Context ledger endpoint
+ * Demonstrates context management capability
+ */
+app.get("/api/v1/context/:ledgerId", (req, res) => {
+    const ledgerId = req.params.ledgerId;
+    // Return mock context ledger
+    res.json({
+        $schema: "https://lafs.dev/schemas/v1/context-ledger.schema.json",
+        ledgerId,
+        version: 1,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        entries: [],
+        checksum: "sha256:mock",
+        maxEntries: 1000
+    });
+});
+app.post("/api/v1/context/:ledgerId/entries", express.json(), (req, res) => {
+    const ledgerId = req.params.ledgerId;
+    const entry = req.body;
+    res.json({
+        $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+        _meta: {
+            specVersion: "1.0.0",
+            schemaVersion: "1.0.0",
+            timestamp: new Date().toISOString(),
+            operation: "context:append",
+            requestId: crypto.randomUUID(),
+            transport: "http",
+            strict: true,
+            mvi: "standard",
+            contextVersion: 2
+        },
+        success: true,
+        result: {
+            ledgerId,
+            entryId: crypto.randomUUID(),
+            committed: true,
+            timestamp: new Date().toISOString()
+        },
+        error: null
+    });
+});
+/**
+ * Discovery configuration
+ * Advertises all LAFS capabilities and endpoints
+ */
+const discoveryConfig = {
+    service: {
+        name: "example-lafs-service",
+        version: "1.0.0",
+        description: "Example LAFS-compliant API service demonstrating discovery protocol"
+    },
+    capabilities: [
+        {
+            name: "envelope-processor",
+            version: "1.0.0",
+            description: "Process and validate LAFS envelopes",
+            operations: ["process", "validate", "transform"]
+        },
+        {
+            name: "context-ledger",
+            version: "1.0.0",
+            description: "Manage context ledgers for stateful operations",
+            operations: ["read", "append", "query"]
+        },
+        {
+            name: "pagination-provider",
+            version: "1.0.0",
+            description: "Provide cursor and offset pagination for list endpoints",
+            operations: ["cursor", "offset", "none"],
+            optional: true
+        }
+    ],
+    endpoints: {
+        envelope: "/api/v1/envelope",
+        context: "/api/v1/context",
+        discovery: "https://lafs.dev/schemas/v1/discovery.schema.json"
+    },
+    cacheMaxAge: 3600,
+    lafsVersion: "1.0.0"
+};
+// Mount discovery middleware BEFORE other routes
+// This ensures /.well-known/lafs.json is served at the root
+app.use(discoveryMiddleware(discoveryConfig));
+/**
+ * Health check endpoint
+ */
+app.get("/health", (req, res) => {
+    res.json({
+        status: "healthy",
+        service: discoveryConfig.service.name,
+        version: discoveryConfig.service.version,
+        timestamp: new Date().toISOString()
+    });
+});
+/**
+ * Error handling middleware
+ */
+app.use((err, req, res, next) => {
+    console.error("Error:", err);
+    res.status(500).json({
+        success: false,
+        error: {
+            code: "INTERNAL_ERROR",
+            message: err.message || "Internal server error",
+            category: "INTERNAL",
+            retryable: false,
+            retryAfterMs: null,
+            details: process.env.NODE_ENV === "development" ? { stack: err.stack } : {}
+        },
+        result: null
+    });
+});
+/**
+ * Start server
+ */
+const server = app.listen(PORT, () => {
+    console.log(`
+╔════════════════════════════════════════════════════════╗
+║     LAFS Discovery Server Running                      ║
+╠════════════════════════════════════════════════════════╣
+║  Service:    ${discoveryConfig.service.name.padEnd(43)}║
+║  Version:    ${discoveryConfig.service.version.padEnd(43)}║
+║  Port:       ${String(PORT).padEnd(43)}║
+╠════════════════════════════════════════════════════════╣
+║  Endpoints:                                            ║
+║    GET  /.well-known/lafs.json  (Discovery document)   ║
+║    POST /api/v1/envelope        (Envelope processor)   ║
+║    GET  /api/v1/context/:id     (Context ledger)       ║
+║    GET  /health                 (Health check)         ║
+╚════════════════════════════════════════════════════════╝
+
+Test with:
+  curl http://localhost:${PORT}/.well-known/lafs.json | jq
+  curl http://localhost:${PORT}/health | jq
+  curl -X POST http://localhost:${PORT}/api/v1/envelope \
+    -H "Content-Type: application/json" \
+    -d '{"_meta":{"operation":"test","requestId":"123"},"payload":{"hello":"world"}}'
+`);
+});
+/**
+ * Graceful shutdown
+ */
+process.on("SIGTERM", () => {
+    console.log("\nShutting down gracefully...");
+    server.close(() => {
+        console.log("Server closed");
+        process.exit(0);
+    });
+});
+process.on("SIGINT", () => {
+    console.log("\nShutting down gracefully...");
+    server.close(() => {
+        console.log("Server closed");
+        process.exit(0);
+    });
+});
+export default app;

package/dist/examples/mcp-lafs-client.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * MCP-LAFS Client Example
+ *
+ * A client that connects to the MCP-LAFS server and validates responses
+ * are LAFS-compliant. Demonstrates budget negotiation and envelope validation.
+ *
+ * Usage: npx ts-node examples/mcp-lafs-client.ts
+ */
+export {};