LAFS Protocol

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 and A2A by standardizing what comes back — not how it gets there.

Current version: 1.3.1 | 📚 Documentation | Spec | Migration Guides

What LAFS provides

| Layer | Files | Description | |-------|-------|-------------| | 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 | | 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 with guides, SDK reference, and specs |

Install

npm install @cleocode/lafs-protocol

Usage

import {
  validateEnvelope,
  runEnvelopeConformance,
  isRegisteredErrorCode,
} from "@cleocode/lafs-protocol";

// Validate an envelope against the schema
const result = validateEnvelope(envelope);
if (!result.valid) {
  console.error(result.errors);
}

// Run full conformance suite (schema + invariants + error codes + strict mode + pagination)
const report = runEnvelopeConformance(envelope);
console.log(report.ok); // true if all checks pass

CLI

# 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

{
  "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
  "_meta": {
    "specVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "timestamp": "2026-02-13T00:00:00Z",
    "operation": "example.list",
    "requestId": "req_01",
    "transport": "http",
    "strict": true,
    "mvi": "standard",
    "contextVersion": 1
  },
  "success": true,
  "result": { "items": [{ "id": "1", "title": "Example" }] },
  "page": {
    "mode": "cursor",
    "nextCursor": "eyJpZCI6IjEwIn0=",
    "hasMore": true
  }
}

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
• 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

A2A Integration

LAFS integrates with the A2A Protocol via @a2a-js/sdk. Import from the @cleocode/lafs-protocol/a2a subpath:

import {
  // Extensions
  buildLafsExtension,
  extensionNegotiationMiddleware,
  LAFS_EXTENSION_URI,

  // Task lifecycle
  TaskManager,
  attachLafsEnvelope,
  isTerminalState,

  // Protocol bindings
  getErrorCodeMapping,
  createJsonRpcRequest,
  createProblemDetails,
} from "@cleocode/lafs-protocol/a2a";

Agent Card with LAFS extension — use autoIncludeLafsExtension in discovery config:

import { discoveryMiddleware } from "@cleocode/lafs-protocol/discovery";

app.use(discoveryMiddleware({
  agent: { name: "my-agent", /* ... */ },
  autoIncludeLafsExtension: true,
}));

Protocol bindings are also available as a standalone subpath:

import { getErrorCodeMapping } from "@cleocode/lafs-protocol/a2a/bindings";

Conformance checks

| Check | Description | Tier | |-------|-------------|------| | envelope_schema_valid | Validates against JSON Schema | Core | | envelope_invariants | success/result/error consistency | Core | | error_code_registered | Error code exists in registry | Core | | meta_mvi_present | Valid MVI disclosure level | Standard | | meta_strict_present | Strict mode declared | Standard | | strict_mode_behavior | Optional fields omitted (not null) in strict mode | Standard | | strict_mode_enforced | Additional properties rejected/allowed per mode | Standard | | pagination_mode_consistent | Page fields match declared mode | Standard |

Project layout

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
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
  discovery.ts                   # A2A Agent Card discovery middleware
  cli.ts                         # CLI diagnostic tool
  a2a/
    bridge.ts                    # A2A SDK integration & result wrapper
    extensions.ts                # Extension negotiation & LAFS extension builder
    task-lifecycle.ts            # Task state machine & lifecycle management
    bindings/
      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

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 |

License

MIT