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.5.0 | 📚 Documentation | Spec | Migration Guides
| 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 |
npm install @cleocode/lafs-protocolimport {
createEnvelope,
parseLafsResponse,
LafsError,
validateEnvelope,
runEnvelopeConformance,
isRegisteredErrorCode,
} from "@cleocode/lafs-protocol";
// Build envelope with defaults
const envelope = createEnvelope({
success: true,
result: { items: [] },
meta: { operation: "example.list", requestId: "req_1" },
});
// Validate an envelope against the schema
const validation = validateEnvelope(envelope);
if (!validation.valid) {
console.error(validation.errors);
}
// Parse envelope responses with one function
try {
const parsed = parseLafsResponse(envelope);
console.log(parsed);
} catch (error) {
if (error instanceof LafsError) {
console.error(error.code, error.message);
}
}
// Run full conformance suite (schema + invariants + error codes + strict mode + pagination)
const report = runEnvelopeConformance(envelope);
console.log(report.ok); // true if all checks passdocs/guides/llm-agent-guide.md- parser, success/error handling, strict JSON policydocs/guides/schema-extension.md- operation-specific result validation on top of core schemadocs/guides/compliance-pipeline.md- generation middleware with validate + conformance gatesdocs/llms.txt- LLM-oriented index and canonical sources
# Run conformance checks on a fixture
npm run conformance -- --envelope fixtures/valid-success-envelope.json
# Run tests
npm test
# Type check
npm run typecheck{
"$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
}
}- Conditional pagination — cursor, offset, and none modes with mode-specific required fields
- Strict/lenient mode —
strict: truerejects unknown properties;strict: falseallows them - MVI disclosure levels —
minimal,standard,full,customcontrol 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 —
_extensionsfield 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
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";| 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 |
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 | 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 |
MIT