@cleocode/lafs 2026.3.74 → 2026.4.3

package/README.md

@@ -1,12 +1,11 @@
 # LAFS Protocol
 
-**LLM-Agent-First Specification** — a response envelope contract for AI agent systems.
+**LLM-Agent-First Specification** -- a response envelope contract for AI agent systems.
 
-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.
+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:** 1.5.0 | [📚 Documentation](https://codluv.gitbook.io/lafs/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 2026.4.0 | [Spec](lafs.md)
 
-[![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs/)
 [![npm](https://img.shields.io/npm/v/@cleocode/lafs)](https://www.npmjs.com/package/@cleocode/lafs)
 
 ## What LAFS provides
@@ -16,17 +15,24 @@ LAFS defines a standard envelope format for structured responses from LLM-powere
 | **Spec** | `lafs.md` | Protocol specification with RFC 2119 language |
 | **Schemas** | `schemas/v1/envelope.schema.json` | Envelope schema (Draft-07) with conditional pagination validation |
 | | `schemas/v1/context-ledger.schema.json` | Context ledger for state tracking across request/response cycles |
-| | `schemas/v1/error-registry.json` | 12 registered error codes with HTTP/gRPC/CLI transport mappings |
+| | `schemas/v1/discovery.schema.json` | Agent Card discovery schema |
+| | `schemas/v1/conformance-profiles.json` | Conformance tier definitions |
+| | `schemas/v1/error-registry.json` | 13 registered error codes with HTTP/gRPC/CLI transport mappings |
 | **Tooling** | `src/` | TypeScript validation, conformance runner, CLI diagnostic tool |
-| **A2A** | `src/a2a/` | Agent-to-Agent integration: extensions, task lifecycle, protocol bindings (JSON-RPC/HTTP/gRPC) |
-| **Tests** | `tests/` | Tests covering envelope, pagination, strict mode, error handling, A2A extensions, task lifecycle, bindings |
-| **Fixtures** | `fixtures/` | 14 JSON fixtures (valid + invalid) for conformance testing |
-| **Docs** | `docs/` | [GitBook documentation](https://codluv.gitbook.io/lafs/) with guides, SDK reference, and specs |
+| **A2A** | `src/a2a/` | Agent-to-Agent integration: extensions, task lifecycle, streaming, protocol bindings (JSON-RPC/HTTP/gRPC) |
+| **Tests** | `tests/` | 20 test suites covering envelope, pagination, strict mode, error handling, A2A extensions, task lifecycle, bindings |
+| **Fixtures** | `fixtures/` | 25 JSON fixtures (valid + invalid + agent workflow scenarios) for conformance testing |
+| **Docs** | `docs/` | Guides, SDK reference, architecture docs, and specs |
 
 ## Install
 
 ```bash
+# Inside the monorepo (pnpm workspace)
+pnpm add @cleocode/lafs
+
+# External consumers
 npm install @cleocode/lafs
+# or: yarn add @cleocode/lafs
 ```
 
 ## Usage
@@ -41,7 +47,7 @@ import {
   isRegisteredErrorCode,
 } from "@cleocode/lafs";
 
-// Build envelope with defaults
+// Build a success envelope
 const envelope = createEnvelope({
   success: true,
   result: { items: [] },
@@ -54,7 +60,7 @@ if (!validation.valid) {
   console.error(validation.errors);
 }
 
-// Parse envelope responses with one function
+// Parse envelope responses
 try {
   const parsed = parseLafsResponse(envelope);
   console.log(parsed);
@@ -69,26 +75,6 @@ const report = runEnvelopeConformance(envelope);
 console.log(report.ok); // true if all checks pass
 ```
 
-## LLM-agent implementation guides
-
-- `docs/guides/llm-agent-guide.md` - parser, success/error handling, strict JSON policy
-- `docs/guides/schema-extension.md` - operation-specific result validation on top of core schema
-- `docs/guides/compliance-pipeline.md` - generation middleware with validate + conformance gates
-- `docs/llms.txt` - LLM-oriented index and canonical sources
-
-## CLI
-
-```bash
-# Run conformance checks on a fixture
-npm run conformance -- --envelope fixtures/valid-success-envelope.json
-
-# Run tests
-npm test
-
-# Type check
-npm run typecheck
-```
-
 ## Envelope structure
 
 ```json
@@ -115,17 +101,28 @@ npm run typecheck
 }
 ```
 
+### Envelope invariants
+
+- `$schema`, `_meta`, `success`, and `result` are always required.
+- `success: true` implies `error` is `null` (or absent).
+- `success: false` requires a non-null `error` object. `result` MAY be non-null on error envelopes -- this allows validation tools to include actionable data (e.g., suggested fixes) alongside error metadata.
+- Exactly one pagination mode (`cursor`, `offset`, `none`) with mode-specific required fields.
+- `strict: true` rejects additional properties; `strict: false` allows them.
+
 ## Key features
 
-- **Conditional pagination** — cursor, offset, and none modes with mode-specific required fields
-- **Strict/lenient mode** — `strict: true` rejects unknown properties; `strict: false` allows them
-- **MVI disclosure levels** — `minimal`, `standard`, `full`, `custom` control response verbosity
+- **Conditional pagination** -- cursor, offset, and none modes with mode-specific required fields
+- **Strict/lenient mode** -- `strict: true` rejects unknown properties; `strict: false` allows them
+- **MVI disclosure levels** -- `minimal`, `standard`, `full`, `custom` control response verbosity
 - **Field selection** (`_fields`) and **expansion** (`_expand`) request parameters
-- **Context ledger** — tracks state across request/response cycles with monotonic versioning
-- **Error registry** — 12 codes with category, retryability, and transport-specific status mappings
-- **Extension mechanism** — `_extensions` field for vendor metadata (`x-` prefix convention)
-- **Adoption tiers** — Core, Standard, Complete with progressive conformance requirements
-- **A2A integration** — Agent Card discovery, extension negotiation, task lifecycle management, protocol bindings
+- **Context ledger** -- tracks state across request/response cycles with monotonic versioning
+- **Error registry** -- 13 codes with category, retryability, agent action, and transport-specific status mappings
+- **Extension mechanism** -- `_extensions` field for vendor metadata (`x-` prefix convention)
+- **Adoption tiers** -- Core, Standard, Complete with progressive conformance requirements
+- **A2A integration** -- Agent Card discovery, extension negotiation, task lifecycle management, protocol bindings
+- **Operations and reliability** -- circuit breaker, health checks, graceful shutdown, budget enforcement, token estimation
+- **MCP adapter** -- wrap LAFS envelopes for Model Context Protocol tool responses
+- **Problem Details** -- RFC 9457 Problem Details generation from LAFS errors
 
 ## A2A Integration
 
@@ -150,7 +147,7 @@ import {
 } from "@cleocode/lafs/a2a";
 ```
 
-**Agent Card with LAFS extension** — use `autoIncludeLafsExtension` in discovery config:
+**Agent Card with LAFS extension** -- use `autoIncludeLafsExtension` in discovery config:
 
 ```typescript
 import { discoveryMiddleware } from "@cleocode/lafs/discovery";
@@ -167,6 +164,19 @@ app.use(discoveryMiddleware({
 import { getErrorCodeMapping } from "@cleocode/lafs/a2a/bindings";
 ```
 
+## CLI
+
+```bash
+# Run conformance checks on a fixture
+pnpm run conformance -- --envelope fixtures/valid-success-envelope.json
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm run typecheck
+```
+
 ## Conformance checks
 
 | Check | Description | Tier |
@@ -187,48 +197,67 @@ lafs.md                          # Protocol specification
 schemas/v1/
   envelope.schema.json           # Envelope schema (Draft-07)
   context-ledger.schema.json     # Context ledger schema
-  error-registry.json            # Error code registry
+  discovery.schema.json          # Agent Card discovery schema
+  conformance-profiles.json      # Conformance tier definitions
+  agent-card.schema.json         # Agent Card schema
+  error-registry.json            # Error code registry (13 codes)
 src/
-  types.ts                       # TypeScript types (discriminated unions)
-  validateEnvelope.ts            # Ajv-based schema validator
-  conformance.ts                 # Conformance runner (8 checks)
-  errorRegistry.ts               # Error code helpers
-  flagSemantics.ts               # Format flag resolution
+  index.ts                       # Barrel export (all public API)
+  types.ts                       # Core types (LAFSEnvelope, LAFSError, etc.)
+  envelope.ts                    # createEnvelope(), parseLafsResponse(), LafsError
+  validateEnvelope.ts            # Schema validator (native Rust via napi-rs, AJV fallback)
+  conformance.ts                 # Conformance runner (runEnvelopeConformance)
+  conformanceProfiles.ts         # Tier-based conformance profile definitions
+  compliance.ts                  # Compliance pipeline utilities
+  errorRegistry.ts               # Error code helpers (getRegistryCode, isRegisteredErrorCode)
+  flagSemantics.ts               # Format flag resolution (--json / --human)
+  flagResolver.ts                # Flag resolution with config precedence
+  fieldExtraction.ts             # _fields / _expand parameter extraction
+  mviProjection.ts               # MVI disclosure level projection
+  tokenEstimator.ts              # Token budget estimation
+  budgetEnforcement.ts           # Token budget enforcement
+  problemDetails.ts              # RFC 9457 Problem Details from LAFS errors
+  deprecationRegistry.ts         # Deprecation tracking and warnings
+  native-loader.ts               # Lazy native Rust validator loader
   discovery.ts                   # A2A Agent Card discovery middleware
-  cli.ts                         # CLI diagnostic tool
+  cli.ts                         # CLI diagnostic tool (lafs-conformance)
+  health/index.ts                # Health check endpoint
+  circuit-breaker/index.ts       # Circuit breaker pattern
+  shutdown/index.ts              # Graceful shutdown handler
   a2a/
+    index.ts                     # A2A barrel export
     bridge.ts                    # A2A SDK integration & result wrapper
     extensions.ts                # Extension negotiation & LAFS extension builder
     task-lifecycle.ts            # Task state machine & lifecycle management
+    streaming.ts                 # SSE/streaming task event support
     bindings/
+      index.ts                   # Barrel export & cross-binding error mapping
       jsonrpc.ts                 # JSON-RPC 2.0 method/error constants & builders
       http.ts                    # HTTP endpoints, RFC 9457 Problem Details
       grpc.ts                    # gRPC status codes & service definitions (types only)
-      index.ts                   # Barrel export & cross-binding error mapping
-tests/                           # Tests (vitest)
-fixtures/                        # JSON test fixtures
-docs/
-  POSITIONING.md                 # MCP/A2A complementary positioning
-  VISION.md                      # Project vision and primary persona
-  CONFORMANCE.md                 # Conformance checks and adoption tiers
-migrations/
-  v0.3.0-to-v0.4.0.md           # Envelope rationalization migration
-  v0.4.0-to-v0.5.0.md           # Pagination & MVI schema migration
-CONTRIBUTING.md                  # Contributor guidelines, RFC process
+tests/                           # 20 test suites (vitest)
+fixtures/                        # 25 JSON fixtures (valid + invalid + agent workflows)
+docs/                            # Guides, architecture, SDK reference
+CONTRIBUTING.md                  # Contributor guidelines
 ```
 
 ## Version history
 
-| Version | Phase | Description |
-|---------|-------|-------------|
-| **v1.2.3** | **4** | **A2A v1.0+ compliance: extension negotiation, task lifecycle, protocol bindings (JSON-RPC/HTTP/gRPC)** |
-| 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 |
-| v0.2.0 | 0 | Protocol cleanup, fixtures, governance, security considerations |
-| v0.1.1 | — | Initial npm publish |
-| v0.1.0 | — | Bootstrap |
+| Version | Description |
+|---------|-------------|
+| **2026.4.0** | CalVer adoption. Operations and reliability modules (circuit breaker, health, shutdown, budget enforcement). MCP adapter. Problem Details (RFC 9457). Streaming support. |
+| 1.8.0 | Error envelopes MAY include non-null `result` for actionable data alongside error metadata. |
+| 1.5.0 | Agent workflows fixtures. Deprecation registry. Field extraction. MVI projection. |
+| 1.2.3 | A2A v1.0+ compliance: extension negotiation, task lifecycle, protocol bindings (JSON-RPC/HTTP/gRPC). |
+| 1.0.0 | Production release: token budgets, agent discovery, MCP integration. |
+| 0.5.0 | Conditional pagination, MVI field selection/expansion, context ledger schema. |
+| 0.4.0 | Optional page/error, extensions, strict/lenient mode, warnings. |
+| 0.3.0 | Strategic positioning, vision alignment, adoption tiers. |
+| 0.1.0 | Initial release. |
+
+## Repository
+
+This package lives at [`packages/lafs`](https://github.com/kryptobaseddev/cleo/tree/main/packages/lafs) in the [kryptobaseddev/cleo](https://github.com/kryptobaseddev/cleo) monorepo.
 
 ## License
 

package/dist/schemas/v1/agent-card.schema.json

@@ -0,0 +1,230 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://lafs.dev/schemas/v1/agent-card.schema.json",
+    "title": "A2A Agent Card v1.0",
+    "description": "A2A-compliant Agent Card schema for agent discovery. Reference: specs/external/specification.md",
+    "type": "object",
+    "required": [
+        "name",
+        "description",
+        "version",
+        "url",
+        "capabilities",
+        "defaultInputModes",
+        "defaultOutputModes",
+        "skills"
+    ],
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "format": "uri",
+            "description": "JSON Schema URL"
+        },
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "description": "Human-readable agent name"
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048,
+            "description": "Detailed description of agent capabilities"
+        },
+        "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+$",
+            "description": "Agent version (SemVer)"
+        },
+        "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Base URL for A2A endpoints"
+        },
+        "provider": {
+            "type": "object",
+            "required": ["organization", "url"],
+            "properties": {
+                "organization": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Organization name"
+                },
+                "url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "Organization URL"
+                }
+            }
+        },
+        "capabilities": {
+            "type": "object",
+            "required": [],
+            "properties": {
+                "streaming": {
+                    "type": "boolean",
+                    "description": "Supports streaming responses"
+                },
+                "pushNotifications": {
+                    "type": "boolean",
+                    "description": "Supports push notifications"
+                },
+                "extendedAgentCard": {
+                    "type": "boolean",
+                    "description": "Supports extended agent card"
+                },
+                "extensions": {
+                    "type": "array",
+                    "description": "Supported extensions",
+                    "items": {
+                        "type": "object",
+                        "required": ["uri", "description", "required"],
+                        "properties": {
+                            "uri": {
+                                "type": "string",
+                                "format": "uri",
+                                "description": "Extension URI (unique identifier)"
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Human-readable description"
+                            },
+                            "required": {
+                                "type": "boolean",
+                                "description": "Whether the extension is required"
+                            },
+                            "params": {
+                                "type": "object",
+                                "description": "Extension-specific parameters"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "defaultInputModes": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Supported input content types",
+            "items": {
+                "type": "string",
+                "description": "MIME type"
+            }
+        },
+        "defaultOutputModes": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Supported output content types",
+            "items": {
+                "type": "string",
+                "description": "MIME type"
+            }
+        },
+        "skills": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Agent skills/capabilities",
+            "items": {
+                "type": "object",
+                "required": ["id", "name", "description", "tags"],
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Skill unique identifier"
+                    },
+                    "name": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Human-readable name"
+                    },
+                    "description": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Detailed description"
+                    },
+                    "tags": {
+                        "type": "array",
+                        "minItems": 1,
+                        "description": "Keywords/tags",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "examples": {
+                        "type": "array",
+                        "description": "Example prompts",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "inputModes": {
+                        "type": "array",
+                        "description": "Supported input modes (overrides agent defaults)",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "outputModes": {
+                        "type": "array",
+                        "description": "Supported output modes (overrides agent defaults)",
+                        "items": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "securitySchemes": {
+            "type": "object",
+            "description": "Security authentication schemes (OpenAPI 3.0 style)",
+            "additionalProperties": {
+                "type": "object",
+                "required": ["type"],
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["http", "apiKey", "oauth2", "openIdConnect"],
+                        "description": "Security scheme type"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Description"
+                    },
+                    "scheme": {
+                        "type": "string",
+                        "description": "HTTP scheme (e.g., bearer)"
+                    },
+                    "bearerFormat": {
+                        "type": "string",
+                        "description": "Bearer token format (e.g., JWT)"
+                    }
+                }
+            }
+        },
+        "security": {
+            "type": "array",
+            "description": "Required security schemes",
+            "items": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "documentationUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Documentation URL"
+        },
+        "iconUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Icon URL"
+        }
+    }
+}

package/dist/schemas/v1/context-ledger.schema.json

@@ -0,0 +1,70 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://lafs.dev/schemas/v1/context-ledger.schema.json",
+    "title": "LAFS Context Ledger",
+    "description": "Tracks state across request/response cycles for context preservation",
+    "type": "object",
+    "required": ["ledgerId", "version", "createdAt", "updatedAt", "entries", "checksum", "maxEntries"],
+    "properties": {
+        "ledgerId": {
+            "type": "string",
+            "description": "Unique identifier for this context ledger instance"
+        },
+        "version": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Monotonically increasing version number matching _meta.contextVersion"
+        },
+        "createdAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when the ledger was created"
+        },
+        "updatedAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the last ledger update"
+        },
+        "entries": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["entryId", "timestamp", "operation", "contextDelta"],
+                "properties": {
+                    "entryId": {
+                        "type": "string",
+                        "description": "Unique identifier for this ledger entry"
+                    },
+                    "timestamp": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "operation": {
+                        "type": "string",
+                        "description": "The operation that generated this entry"
+                    },
+                    "contextDelta": {
+                        "type": "object",
+                        "description": "The context changes introduced by this operation",
+                        "additionalProperties": true
+                    },
+                    "requestId": {
+                        "type": "string",
+                        "description": "Correlation with the request that produced this entry"
+                    }
+                }
+            },
+            "description": "Ordered array of context entries (append-only)"
+        },
+        "checksum": {
+            "type": "string",
+            "description": "Integrity checksum of the ledger contents"
+        },
+        "maxEntries": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum number of entries before truncation/compaction"
+        }
+    },
+    "additionalProperties": false
+}