@cleocode/lafs-protocol 1.0.0 → 1.2.0

package/dist/src/shutdown/index.js

@@ -0,0 +1,160 @@
+/**
+ * LAFS Graceful Shutdown Module
+ *
+ * Handles graceful shutdown of LAFS servers
+ */
+const state = {
+    isShuttingDown: false,
+    activeConnections: 0
+};
+/**
+ * Enable graceful shutdown for an HTTP server
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { gracefulShutdown } from '@cleocode/lafs-protocol/shutdown';
+ *
+ * const app = express();
+ * const server = app.listen(3000);
+ *
+ * gracefulShutdown(server, {
+ *   timeout: 30000,
+ *   signals: ['SIGTERM', 'SIGINT'],
+ *   onShutdown: async () => {
+ *     console.log('Shutting down...');
+ *     await db.close();
+ *   }
+ * });
+ * ```
+ */
+export function gracefulShutdown(server, config = {}) {
+    const { timeout = 30000, signals = ['SIGTERM', 'SIGINT'], onShutdown, onClose } = config;
+    // Track active connections
+    server.on('connection', (socket) => {
+        if (state.isShuttingDown) {
+            socket.destroy();
+            return;
+        }
+        state.activeConnections++;
+        socket.on('close', () => {
+            state.activeConnections--;
+        });
+    });
+    // Handle shutdown signals
+    signals.forEach((signal) => {
+        process.on(signal, async () => {
+            console.log(`${signal} received, starting graceful shutdown...`);
+            await performShutdown(server, timeout, onShutdown, onClose);
+        });
+    });
+    // Handle uncaught errors
+    process.on('uncaughtException', async (error) => {
+        console.error('Uncaught exception:', error);
+        await performShutdown(server, timeout, onShutdown, onClose);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        console.error('Unhandled rejection:', reason);
+        await performShutdown(server, timeout, onShutdown, onClose);
+    });
+}
+async function performShutdown(server, timeout, onShutdown, onClose) {
+    if (state.isShuttingDown) {
+        console.log('Shutdown already in progress...');
+        return;
+    }
+    state.isShuttingDown = true;
+    state.shutdownStartTime = new Date();
+    try {
+        // Call user shutdown handler
+        if (onShutdown) {
+            await Promise.race([
+                onShutdown(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Shutdown timeout')), timeout))
+            ]);
+        }
+        // Stop accepting new connections
+        server.close((err) => {
+            if (err) {
+                console.error('Error closing server:', err);
+            }
+            else {
+                console.log('Server closed');
+            }
+        });
+        // Wait for active connections to close
+        const startTime = Date.now();
+        while (state.activeConnections > 0 && Date.now() - startTime < timeout) {
+            console.log(`Waiting for ${state.activeConnections} connections to close...`);
+            await sleep(1000);
+        }
+        if (state.activeConnections > 0) {
+            console.warn(`Forcing shutdown with ${state.activeConnections} active connections`);
+        }
+        // Call user close handler
+        if (onClose) {
+            await onClose();
+        }
+        console.log('Graceful shutdown complete');
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error during shutdown:', error);
+        process.exit(1);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Check if server is shutting down
+ */
+export function isShuttingDown() {
+    return state.isShuttingDown;
+}
+/**
+ * Get shutdown state
+ */
+export function getShutdownState() {
+    return { ...state };
+}
+/**
+ * Force immediate shutdown (emergency use only)
+ */
+export function forceShutdown(exitCode = 1) {
+    console.log('Force shutting down...');
+    process.exit(exitCode);
+}
+/**
+ * Middleware to reject requests during shutdown
+ *
+ * @example
+ * ```typescript
+ * app.use(shutdownMiddleware());
+ * ```
+ */
+export function shutdownMiddleware() {
+    return (req, res, next) => {
+        if (state.isShuttingDown) {
+            res.status(503).json({
+                error: 'Service is shutting down',
+                status: 'unavailable'
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Wait for shutdown to complete
+ *
+ * @example
+ * ```typescript
+ * await waitForShutdown();
+ * ```
+ */
+export async function waitForShutdown() {
+    while (!state.isShuttingDown) {
+        await sleep(100);
+    }
+}

package/dist/src/types.d.ts

@@ -17,6 +17,8 @@ export interface LAFSMeta {
     strict: boolean;
     mvi: 'minimal' | 'standard' | 'full' | 'custom';
     contextVersion: number;
+    /** Session identifier for correlating multi-step agent workflows */
+    sessionId?: string;
     warnings?: Warning[];
 }
 export interface LAFSError {
@@ -76,6 +78,8 @@ export interface FlagInput {
     humanFlag?: boolean;
     projectDefault?: "json" | "human";
     userDefault?: "json" | "human";
+    /** Suppress non-essential output for scripting. When true, only essential data is returned. */
+    quiet?: boolean;
 }
 export interface ConformanceReport {
     ok: boolean;

package/lafs.md

@@ -1,5 +1,8 @@
 # LAFS: LLM-Agent-First Specification
 
+> 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
+> **Version:** 1.2.0 | **Status:** Production Ready
+
 ## 1. Scope
 
 LAFS is a **response envelope contract specification**. It defines the canonical shape of structured responses — success envelopes, error envelopes, pagination metadata, and context preservation — for software systems whose primary consumer is an LLM agent or AI-driven tool.
@@ -64,6 +67,52 @@ The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC
 3. Global/user config
 4. Protocol default (`json`)
 
+### 5.3 Supported formats
+
+LAFS supports exactly two output formats:
+
+- **`json`** (default) — Machine-readable JSON envelope for programmatic consumption
+- **`human`** — Human-readable text output for terminal display
+
+#### 5.3.1 Human format definition
+
+The `human` format produces plain text output optimized for terminal display:
+
+- Suitable for direct human consumption in CLI environments
+- NOT markdown, NOT tables, NOT structured data
+- May include ANSI colors (respect `NO_COLOR` environment variable)
+- Example: Tabular data displayed with aligned columns using spaces
+
+```
+ID    Name          Status
+----  ------------  --------
+123   Alpha         active
+456   Beta          pending
+```
+
+#### 5.3.2 Rejected formats
+
+The following formats were explicitly rejected to maintain protocol minimalism:
+
+| Format | Status | Rationale |
+|--------|--------|-----------|
+| `text` | ❌ Rejected | Ambiguous overlap with `human`. Use `human` format with `NO_COLOR=1` for plain text. |
+| `markdown` | ❌ Rejected | Presentation format, not data format. Generate from JSON if markdown rendering is needed. |
+| `table` | ❌ Rejected | Presentation concern. Use `jq` + `column` command or `human` format for tabular display. |
+| `jsonl` | ❌ Rejected | Streaming format violates LAFS discrete envelope contract (see Section 2: Non-Goals). |
+
+**Design principle:** LAFS is a response envelope contract, not a presentation layer. Six formats = format proliferation = protocol bloat.
+
+#### 5.3.3 Achieving presentation goals with json format
+
+Consumers needing presentation formats should:
+
+1. Request `json` format from LAFS-compliant services
+2. Transform JSON to desired presentation format using standard tools:
+   - **Markdown:** `jq` + template engine
+   - **Tables:** `jq` + `column` command
+   - **Plain text:** `jq` with `-r` (raw) output
+
 ---
 
 ## 6. Canonical Response Envelope
@@ -107,6 +156,144 @@ The envelope supports an optional `_extensions` object for vendor-specific metad
 - Consumers MUST NOT rely on extension fields for protocol-required behavior.
 - Producers MAY omit `_extensions` entirely; the field is always optional.
 
+#### 6.2.1 Extension use cases
+
+The following examples demonstrate common use cases for `_extensions`. These fields were rejected from the core protocol but are valid extension use cases.
+
+**Example 1: Performance timing**
+
+```typescript
+// Extension type definition
+interface XTimingExtension {
+  "x-timing": {
+    executionMs: number;        // Total request execution time
+    parseMs?: number;           // Input parsing time
+    queryMs?: number;           // Database query time
+    serializeMs?: number;       // Response serialization time
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-timing": {
+      "executionMs": 42,
+      "queryMs": 15,
+      "serializeMs": 3
+    }
+  }
+}
+```
+
+**Example 2: Source metadata**
+
+```typescript
+interface XSourceExtension {
+  "x-source": {
+    gitRef?: string;           // Git commit SHA
+    apiVersion?: string;       // API implementation version
+    buildTimestamp?: string;   // ISO 8601 build time
+    deployment?: string;       // Deployment environment (staging, prod)
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-source": {
+      "gitRef": "abc123def456",
+      "apiVersion": "2.1.0",
+      "deployment": "production"
+    }
+  }
+}
+```
+
+**Example 3: Applied filters**
+
+```typescript
+interface XFiltersExtension {
+  "x-filters": {
+    applied: Array<{
+      field: string;
+      operator: "eq" | "neq" | "gt" | "lt" | "contains";
+      value: unknown;
+    }>;
+    omitted: string[];         // Fields excluded due to permissions
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-filters": {
+      "applied": [
+        { "field": "status", "operator": "eq", "value": "active" },
+        { "field": "createdAt", "operator": "gt", "value": "2024-01-01" }
+      ],
+      "omitted": ["internalNotes", "costCenter"]
+    }
+  }
+}
+```
+
+**Example 4: Result summary**
+
+```typescript
+interface XSummaryExtension {
+  "x-summary": {
+    totalCount: number;        // Total matching records
+    returnedCount: number;     // Records in this response
+    aggregated?: {
+      revenue?: number;
+      count?: number;
+      average?: number;
+    };
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-summary": {
+      "totalCount": 150,
+      "returnedCount": 25,
+      "aggregated": {
+        "revenue": 125000.00,
+        "average": 833.33
+      }
+    }
+  }
+}
+```
+
+#### 6.2.2 Extension best practices
+
+1. **Use x- prefix** — All extension keys MUST start with `x-` (e.g., `x-caamp-timing`)
+2. **Document your schema** — Publish extension schemas separately from LAFS core
+3. **Don't rely on extensions for core behavior** — Extensions are informational only
+4. **Version your extensions** — Include version in extension key if schema may change (e.g., `x-vendor-v2-field`)
+5. **Keep extensions optional** — Consumers MUST be able to operate without extension data
+6. **Namespace by vendor** — Use vendor prefix to avoid collisions (e.g., `x-caamp-`, `x-acme-`)
+
+#### 6.2.3 When to use extensions vs core protocol
+
+| Use Case | Core Protocol | Extensions |
+|----------|---------------|------------|
+| Session correlation | ✅ sessionId | — |
+| Soft warnings | ✅ warnings array | — |
+| Performance timing | — | ✅ x-timing |
+| Source/version metadata | — | ✅ x-source |
+| Debug filters | — | ✅ x-filters |
+| Derived summaries | — | ✅ x-summary |
+| Data integrity (TLS covers) | — | ✅ x-checksum (if needed) |
+
+**Guideline:** If a field is required for basic operation, it belongs in core. If it's useful for debugging, monitoring, or rich display, it belongs in extensions.
+
 ---
 
 ## 7. Error Contract

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",
@@ -23,7 +23,7 @@
     "type": "git",
     "url": "git+https://github.com/kryptobaseddev/lafs-protocol.git"
   },
-  "homepage": "https://github.com/kryptobaseddev/lafs-protocol#readme",
+  "homepage": "https://codluv.gitbook.io/lafs-protocol/",
   "bugs": {
     "url": "https://github.com/kryptobaseddev/lafs-protocol/issues"
   },
@@ -60,6 +60,7 @@
     "vitest": "^2.1.9"
   },
   "dependencies": {
+    "@a2a-js/sdk": "^0.3.10",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "express": "^5.2.1"

package/schemas/v1/envelope.schema.json

@@ -67,6 +67,12 @@
           "type": "integer",
           "minimum": 0
         },
+        "sessionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Session identifier for correlating multi-step agent workflows"
+        },
         "warnings": {
           "type": "array",
           "items": {