@cleocode/lafs-protocol 1.0.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/src/a2a/bridge.d.ts

@@ -0,0 +1,129 @@
+/**
+ * LAFS A2A Bridge
+ *
+ * Integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * LAFS provides envelope wrapping and token budget support.
+ */
+import { A2AClient } from '@a2a-js/sdk/client';
+import { Artifact, Part, SendMessageResponse, JSONRPCErrorResponse } from '@a2a-js/sdk';
+export interface LafsA2AConfig {
+    defaultBudget?: {
+        maxTokens?: number;
+        maxItems?: number;
+    };
+    envelopeResponses?: boolean;
+}
+export interface LafsEnvelope {
+    $schema: string;
+    _meta: {
+        specVersion: string;
+        operation: string;
+        requestId: string;
+        mvi: string;
+        _tokenEstimate?: {
+            estimated: number;
+            budget?: number;
+        };
+    };
+    success: boolean;
+    result: unknown;
+    error: null | {
+        code: string;
+        message: string;
+        category: string;
+        retryable: boolean;
+    };
+}
+/**
+ * Wrap A2A client with LAFS envelope support
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@lafs/envelope/a2a';
+ *
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://localhost:4000');
+ *
+ * const client = withLafsEnvelope(a2aClient, {
+ *   envelopeResponses: true,
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * const result = await client.sendMessage({
+ *   message: { role: 'user', parts: [{ text: 'Hello' }] }
+ * });
+ *
+ * // Access LAFS envelope
+ * const envelope = result.getLafsEnvelope();
+ * console.log(envelope._meta._tokenEstimate);
+ * ```
+ */
+export declare function withLafsEnvelope(client: A2AClient, config?: LafsA2AConfig): LafsA2AClient;
+export declare class LafsA2AClient {
+    private client;
+    private config;
+    constructor(client: A2AClient, config: LafsA2AConfig);
+    sendMessage(params: {
+        message: {
+            role: 'user' | 'agent';
+            parts: Part[];
+        };
+        budget?: {
+            maxTokens?: number;
+            maxItems?: number;
+        };
+    }): Promise<LafsA2AResult>;
+    private generateId;
+}
+export declare class LafsA2AResult {
+    private result;
+    private budget;
+    constructor(result: SendMessageResponse, budget: {
+        maxTokens?: number;
+        maxItems?: number;
+    });
+    /**
+     * Get the underlying A2A result
+     */
+    getA2AResult(): SendMessageResponse;
+    /**
+     * Check if result is an error
+     */
+    isError(): boolean;
+    /**
+     * Get error details if result is an error
+     */
+    getError(): JSONRPCErrorResponse | null;
+    /**
+     * Extract LAFS envelope from A2A artifact
+     */
+    getLafsEnvelope(): LafsEnvelope | null;
+    /**
+     * Check if result contains LAFS envelope
+     */
+    hasLafsEnvelope(): boolean;
+    /**
+     * Get token estimate from envelope
+     */
+    getTokenEstimate(): {
+        estimated: number;
+        budget?: number;
+    } | null;
+    private isLafsEnvelope;
+}
+/**
+ * Create a LAFS artifact for A2A
+ *
+ * @example
+ * ```typescript
+ * const artifact = createLafsArtifact({
+ *   success: true,
+ *   result: { data: '...' },
+ *   meta: { operation: 'analysis.run' }
+ * });
+ *
+ * task.artifacts.push(artifact);
+ * ```
+ */
+export declare function createLafsArtifact(envelope: LafsEnvelope): Artifact;

package/dist/src/a2a/bridge.js

@@ -0,0 +1,173 @@
+/**
+ * LAFS A2A Bridge
+ *
+ * Integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * LAFS provides envelope wrapping and token budget support.
+ */
+/**
+ * Wrap A2A client with LAFS envelope support
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@lafs/envelope/a2a';
+ *
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://localhost:4000');
+ *
+ * const client = withLafsEnvelope(a2aClient, {
+ *   envelopeResponses: true,
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * const result = await client.sendMessage({
+ *   message: { role: 'user', parts: [{ text: 'Hello' }] }
+ * });
+ *
+ * // Access LAFS envelope
+ * const envelope = result.getLafsEnvelope();
+ * console.log(envelope._meta._tokenEstimate);
+ * ```
+ */
+export function withLafsEnvelope(client, config = {}) {
+    return new LafsA2AClient(client, config);
+}
+export class LafsA2AClient {
+    client;
+    config;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    async sendMessage(params) {
+        // Merge budget with defaults
+        const budget = {
+            ...this.config.defaultBudget,
+            ...params.budget
+        };
+        // Send via official A2A SDK
+        const result = await this.client.sendMessage({
+            message: {
+                kind: 'message',
+                messageId: this.generateId(),
+                role: params.message.role,
+                parts: params.message.parts
+            }
+        });
+        // Wrap result with LAFS envelope support
+        return new LafsA2AResult(result, budget);
+    }
+    generateId() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+}
+export class LafsA2AResult {
+    result;
+    budget;
+    constructor(result, budget) {
+        this.result = result;
+        this.budget = budget;
+    }
+    /**
+     * Get the underlying A2A result
+     */
+    getA2AResult() {
+        return this.result;
+    }
+    /**
+     * Check if result is an error
+     */
+    isError() {
+        return 'error' in this.result;
+    }
+    /**
+     * Get error details if result is an error
+     */
+    getError() {
+        if (this.isError()) {
+            return this.result;
+        }
+        return null;
+    }
+    /**
+     * Extract LAFS envelope from A2A artifact
+     */
+    getLafsEnvelope() {
+        if (this.isError()) {
+            return null;
+        }
+        const successResult = this.result;
+        // Check if result is a Task
+        if (successResult.result?.kind !== 'task') {
+            return null;
+        }
+        const task = successResult.result;
+        if (!task.artifacts || task.artifacts.length === 0) {
+            return null;
+        }
+        // Find LAFS envelope in artifacts
+        for (const artifact of task.artifacts) {
+            for (const part of artifact.parts) {
+                if (part.kind === 'data' && this.isLafsEnvelope(part.data)) {
+                    return part.data;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if result contains LAFS envelope
+     */
+    hasLafsEnvelope() {
+        return this.getLafsEnvelope() !== null;
+    }
+    /**
+     * Get token estimate from envelope
+     */
+    getTokenEstimate() {
+        const envelope = this.getLafsEnvelope();
+        return envelope?._meta?._tokenEstimate ?? null;
+    }
+    isLafsEnvelope(data) {
+        return (typeof data === 'object' &&
+            data !== null &&
+            '$schema' in data &&
+            '_meta' in data &&
+            'success' in data);
+    }
+}
+/**
+ * Create a LAFS artifact for A2A
+ *
+ * @example
+ * ```typescript
+ * const artifact = createLafsArtifact({
+ *   success: true,
+ *   result: { data: '...' },
+ *   meta: { operation: 'analysis.run' }
+ * });
+ *
+ * task.artifacts.push(artifact);
+ * ```
+ */
+export function createLafsArtifact(envelope) {
+    return {
+        artifactId: generateId(),
+        name: 'lafs_response',
+        parts: [{
+                kind: 'data',
+                data: envelope
+            }]
+    };
+}
+function generateId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}

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

@@ -0,0 +1,36 @@
+/**
+ * LAFS Agent-to-Agent (A2A) Integration
+ *
+ * This module provides integration between LAFS and the official
+ * @a2a-js/sdk for Agent-to-Agent communication.
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@cleocode/lafs-protocol/a2a';
+ *
+ * // Create official A2A client
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://agent.example.com');
+ *
+ * // Wrap with LAFS support
+ * const client = withLafsEnvelope(a2aClient, {
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * // Send message
+ * const result = await client.sendMessage({
+ *   message: {
+ *     role: 'user',
+ *     parts: [{ text: 'Analyze data' }]
+ *   }
+ * });
+ *
+ * // Extract LAFS envelope from response
+ * const envelope = result.getLafsEnvelope();
+ * if (envelope) {
+ *   console.log(envelope._meta._tokenEstimate);
+ * }
+ * ```
+ */
+export { withLafsEnvelope, LafsA2AClient, LafsA2AResult, createLafsArtifact, type LafsA2AConfig, type LafsEnvelope } from './bridge.js';

package/dist/src/a2a/index.js

@@ -0,0 +1,36 @@
+/**
+ * LAFS Agent-to-Agent (A2A) Integration
+ *
+ * This module provides integration between LAFS and the official
+ * @a2a-js/sdk for Agent-to-Agent communication.
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@cleocode/lafs-protocol/a2a';
+ *
+ * // Create official A2A client
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://agent.example.com');
+ *
+ * // Wrap with LAFS support
+ * const client = withLafsEnvelope(a2aClient, {
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * // Send message
+ * const result = await client.sendMessage({
+ *   message: {
+ *     role: 'user',
+ *     parts: [{ text: 'Analyze data' }]
+ *   }
+ * });
+ *
+ * // Extract LAFS envelope from response
+ * const envelope = result.getLafsEnvelope();
+ * if (envelope) {
+ *   console.log(envelope._meta._tokenEstimate);
+ * }
+ * ```
+ */
+export { withLafsEnvelope, LafsA2AClient, LafsA2AResult, createLafsArtifact } from './bridge.js';

package/dist/src/circuit-breaker/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * LAFS Circuit Breaker Module
+ *
+ * Provides circuit breaker pattern for resilient service calls
+ */
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export interface CircuitBreakerConfig {
+    name: string;
+    failureThreshold?: number;
+    resetTimeout?: number;
+    halfOpenMaxCalls?: number;
+    successThreshold?: number;
+}
+export interface CircuitBreakerMetrics {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    lastFailureTime?: Date;
+    consecutiveSuccesses: number;
+    totalCalls: number;
+}
+export declare class CircuitBreakerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Circuit breaker for protecting against cascading failures
+ *
+ * @example
+ * ```typescript
+ * import { CircuitBreaker } from '@cleocode/lafs-protocol/circuit-breaker';
+ *
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await externalApi.call();
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit breaker is open');
+ *   }
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime?;
+    private consecutiveSuccesses;
+    private totalCalls;
+    private halfOpenCalls;
+    private resetTimer?;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get current circuit breaker state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit breaker metrics
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Manually open the circuit breaker
+     */
+    forceOpen(): void;
+    /**
+     * Manually close the circuit breaker
+     */
+    forceClose(): void;
+    private onSuccess;
+    private onFailure;
+    private transitionTo;
+    private shouldAttemptReset;
+    private scheduleReset;
+    private reset;
+}
+/**
+ * Circuit breaker registry for managing multiple breakers
+ *
+ * @example
+ * ```typescript
+ * const registry = new CircuitBreakerRegistry();
+ *
+ * registry.add('payment-api', {
+ *   failureThreshold: 3,
+ *   resetTimeout: 60000
+ * });
+ *
+ * const paymentBreaker = registry.get('payment-api');
+ * ```
+ */
+export declare class CircuitBreakerRegistry {
+    private breakers;
+    add(name: string, config: Omit<CircuitBreakerConfig, 'name'>): CircuitBreaker;
+    get(name: string): CircuitBreaker | undefined;
+    getOrCreate(name: string, config: Omit<CircuitBreakerConfig, 'name'>): CircuitBreaker;
+    getAllMetrics(): Record<string, CircuitBreakerMetrics>;
+    resetAll(): void;
+}
+/**
+ * Create a circuit breaker middleware for Express
+ *
+ * @example
+ * ```typescript
+ * app.use('/external-api', circuitBreakerMiddleware({
+ *   name: 'external-api',
+ *   failureThreshold: 5
+ * }));
+ * ```
+ */
+export declare function circuitBreakerMiddleware(config: CircuitBreakerConfig): (req: any, res: any, next: any) => Promise<void>;

package/dist/src/circuit-breaker/index.js

@@ -0,0 +1,249 @@
+/**
+ * LAFS Circuit Breaker Module
+ *
+ * Provides circuit breaker pattern for resilient service calls
+ */
+export class CircuitBreakerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitBreakerError';
+    }
+}
+/**
+ * Circuit breaker for protecting against cascading failures
+ *
+ * @example
+ * ```typescript
+ * import { CircuitBreaker } from '@cleocode/lafs-protocol/circuit-breaker';
+ *
+ * const breaker = new CircuitBreaker({
+ *   name: 'external-api',
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(async () => {
+ *     return await externalApi.call();
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit breaker is open');
+ *   }
+ * }
+ * ```
+ */
+export class CircuitBreaker {
+    config;
+    state = 'CLOSED';
+    failures = 0;
+    successes = 0;
+    lastFailureTime;
+    consecutiveSuccesses = 0;
+    totalCalls = 0;
+    halfOpenCalls = 0;
+    resetTimer;
+    constructor(config) {
+        this.config = config;
+        this.config = {
+            failureThreshold: 5,
+            resetTimeout: 30000,
+            halfOpenMaxCalls: 3,
+            successThreshold: 2,
+            ...config
+        };
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    async execute(fn) {
+        this.totalCalls++;
+        if (this.state === 'OPEN') {
+            if (this.shouldAttemptReset()) {
+                this.transitionTo('HALF_OPEN');
+            }
+            else {
+                throw new CircuitBreakerError(`Circuit breaker '${this.config.name}' is OPEN`);
+            }
+        }
+        if (this.state === 'HALF_OPEN') {
+            if (this.halfOpenCalls >= (this.config.halfOpenMaxCalls || 3)) {
+                throw new CircuitBreakerError(`Circuit breaker '${this.config.name}' is HALF_OPEN (max calls reached)`);
+            }
+            this.halfOpenCalls++;
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Get current circuit breaker state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get circuit breaker metrics
+     */
+    getMetrics() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successes: this.successes,
+            lastFailureTime: this.lastFailureTime,
+            consecutiveSuccesses: this.consecutiveSuccesses,
+            totalCalls: this.totalCalls
+        };
+    }
+    /**
+     * Manually open the circuit breaker
+     */
+    forceOpen() {
+        this.transitionTo('OPEN');
+    }
+    /**
+     * Manually close the circuit breaker
+     */
+    forceClose() {
+        this.transitionTo('CLOSED');
+        this.reset();
+    }
+    onSuccess() {
+        this.successes++;
+        this.consecutiveSuccesses++;
+        if (this.state === 'HALF_OPEN') {
+            if (this.consecutiveSuccesses >= (this.config.successThreshold || 2)) {
+                this.transitionTo('CLOSED');
+                this.reset();
+            }
+        }
+    }
+    onFailure() {
+        this.failures++;
+        this.consecutiveSuccesses = 0;
+        this.lastFailureTime = new Date();
+        if (this.state === 'HALF_OPEN') {
+            this.transitionTo('OPEN');
+            this.scheduleReset();
+        }
+        else if (this.state === 'CLOSED') {
+            if (this.failures >= (this.config.failureThreshold || 5)) {
+                this.transitionTo('OPEN');
+                this.scheduleReset();
+            }
+        }
+    }
+    transitionTo(newState) {
+        console.log(`Circuit breaker '${this.config.name}': ${this.state} -> ${newState}`);
+        this.state = newState;
+        if (newState === 'HALF_OPEN') {
+            this.halfOpenCalls = 0;
+        }
+    }
+    shouldAttemptReset() {
+        if (!this.lastFailureTime)
+            return true;
+        const elapsed = Date.now() - this.lastFailureTime.getTime();
+        return elapsed >= (this.config.resetTimeout || 30000);
+    }
+    scheduleReset() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+        }
+        this.resetTimer = setTimeout(() => {
+            if (this.state === 'OPEN') {
+                this.transitionTo('HALF_OPEN');
+            }
+        }, this.config.resetTimeout || 30000);
+    }
+    reset() {
+        this.failures = 0;
+        this.consecutiveSuccesses = 0;
+        this.halfOpenCalls = 0;
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = undefined;
+        }
+    }
+}
+/**
+ * Circuit breaker registry for managing multiple breakers
+ *
+ * @example
+ * ```typescript
+ * const registry = new CircuitBreakerRegistry();
+ *
+ * registry.add('payment-api', {
+ *   failureThreshold: 3,
+ *   resetTimeout: 60000
+ * });
+ *
+ * const paymentBreaker = registry.get('payment-api');
+ * ```
+ */
+export class CircuitBreakerRegistry {
+    breakers = new Map();
+    add(name, config) {
+        const breaker = new CircuitBreaker({ ...config, name });
+        this.breakers.set(name, breaker);
+        return breaker;
+    }
+    get(name) {
+        return this.breakers.get(name);
+    }
+    getOrCreate(name, config) {
+        let breaker = this.breakers.get(name);
+        if (!breaker) {
+            breaker = this.add(name, config);
+        }
+        return breaker;
+    }
+    getAllMetrics() {
+        const metrics = {};
+        this.breakers.forEach((breaker, name) => {
+            metrics[name] = breaker.getMetrics();
+        });
+        return metrics;
+    }
+    resetAll() {
+        this.breakers.forEach(breaker => breaker.forceClose());
+    }
+}
+/**
+ * Create a circuit breaker middleware for Express
+ *
+ * @example
+ * ```typescript
+ * app.use('/external-api', circuitBreakerMiddleware({
+ *   name: 'external-api',
+ *   failureThreshold: 5
+ * }));
+ * ```
+ */
+export function circuitBreakerMiddleware(config) {
+    const breaker = new CircuitBreaker(config);
+    return async (req, res, next) => {
+        try {
+            await breaker.execute(async () => {
+                next();
+            });
+        }
+        catch (error) {
+            if (error instanceof CircuitBreakerError) {
+                res.status(503).json({
+                    error: 'Service temporarily unavailable',
+                    reason: 'Circuit breaker is open'
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+    };
+}

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

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

@@ -7,3 +7,9 @@ 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/shutdown/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * LAFS Graceful Shutdown Module
+ *
+ * Handles graceful shutdown of LAFS servers
+ */
+import { Server } from 'http';
+export interface GracefulShutdownConfig {
+    timeout?: number;
+    signals?: NodeJS.Signals[];
+    onShutdown?: () => Promise<void> | void;
+    onClose?: () => Promise<void> | void;
+}
+export interface ShutdownState {
+    isShuttingDown: boolean;
+    activeConnections: number;
+    shutdownStartTime?: Date;
+}
+/**
+ * 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 declare function gracefulShutdown(server: Server, config?: GracefulShutdownConfig): void;
+/**
+ * Check if server is shutting down
+ */
+export declare function isShuttingDown(): boolean;
+/**
+ * Get shutdown state
+ */
+export declare function getShutdownState(): ShutdownState;
+/**
+ * Force immediate shutdown (emergency use only)
+ */
+export declare function forceShutdown(exitCode?: number): void;
+/**
+ * Middleware to reject requests during shutdown
+ *
+ * @example
+ * ```typescript
+ * app.use(shutdownMiddleware());
+ * ```
+ */
+export declare function shutdownMiddleware(): (req: any, res: any, next: any) => void;
+/**
+ * Wait for shutdown to complete
+ *
+ * @example
+ * ```typescript
+ * await waitForShutdown();
+ * ```
+ */
+export declare function waitForShutdown(): Promise<void>;

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/lafs.md

@@ -1,5 +1,8 @@
 # LAFS: LLM-Agent-First Specification
 
+> 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
+> **Version:** 1.0.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.0.0",
+  "version": "1.1.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"