@cleocode/lafs-protocol 0.5.0 → 1.1.0

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.
@@ -176,6 +179,56 @@ Rules:
 - Decisions affecting output MUST be represented in ledger state.
 - Missing required context for a mutating step MUST fail with structured error.
 
+### 8.1 Context Retrieval
+
+Agents MAY retrieve context ledger state via `GET /_lafs/context/{ledgerId}` with projection modes.
+
+#### 8.1.1 Projection Modes
+
+**Full Mode (`mode=full`):**
+Returns complete ledger including all entries.
+- Use for: Initial loads, recovery scenarios
+- Supports: Offset-based pagination
+- Response includes: All ledger fields
+
+**Delta Mode (`mode=delta&sinceVersion=N`):**
+Returns only entries added since version N.
+- Use for: Active workflows (efficient sync)
+- Response includes:
+```json
+{
+  "ledgerId": "ctx_abc123",
+  "mode": "delta",
+  "fromVersion": 10,
+  "toVersion": 15,
+  "entries": [/* new entries only */],
+  "removedConstraints": [/* constraints no longer active */],
+  "checksum": "sha256:..."
+}
+```
+
+**Summary Mode (`mode=summary`):**
+Returns checksum and version for validation.
+- Use for: Quick sync validation
+- Response includes only: `ledgerId`, `version`, `checksum`, `entryCount`
+
+#### 8.1.2 Query Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `mode` | enum | `full`, `delta`, `summary` |
+| `sinceVersion` | integer | For delta mode: return entries after this version |
+| `filterByOperation` | string[] | Filter entries by operation name(s) |
+| `limit` | integer | Max entries (1-1000, default 100) |
+| `includeChecksum` | boolean | Include integrity checksum (default true) |
+
+#### 8.1.3 Agent Guidance
+
+- **Initial load**: Use `mode=full` once
+- **Active workflows**: Use `mode=delta` with last known version
+- **Validation**: Use `mode=summary` to verify sync state
+- **Default recommendation**: `delta` mode for agent-optimal behavior
+
 ---
 
 ## 9. MVI and Progressive Disclosure
@@ -212,6 +265,120 @@ Clients MAY request expanded/nested data via the `_expand` request parameter.
 - Pagination mode (offset or cursor) MUST be documented.
 - Mixed pagination modes in one request MUST fail validation.
 
+### 9.5 Token Budget Signaling
+
+Token budget signaling enables clients to declare resource constraints that servers MUST respect when generating responses. This mechanism prevents context window overflow in LLM-driven workflows.
+
+#### 9.5.1 Budget Declaration (`_budget`)
+
+Clients MAY declare resource constraints via the `_budget` request parameter:
+
+```json
+{
+  "_budget": {
+    "maxTokens": 4000,
+    "maxBytes": 32768,
+    "maxItems": 100
+  }
+}
+```
+
+**Fields:**
+- `maxTokens` (integer) - Maximum approximate tokens
+- `maxBytes` (integer) - Maximum byte size
+- `maxItems` (integer) - Maximum items in lists
+
+**Constraints:**
+- At least one field MUST be present
+- All values MUST be positive integers
+- Servers MAY reject budgets exceeding implementation limits
+
+#### 9.5.2 Server Behavior
+
+Servers MUST:
+1. Parse `_budget` from incoming requests
+2. Estimate/measure response size
+3. Return response within budget OR fail with `E_MVI_BUDGET_EXCEEDED`
+
+Servers MAY truncate responses using:
+- **Depth-first**: Remove deepest nested fields
+- **Field priority**: Remove non-essential fields first
+- **Hybrid**: Combine both strategies
+
+When truncation occurs, servers MUST include:
+```json
+{
+  "_meta": {
+    "warnings": [{
+      "code": "E_MVI_BUDGET_TRUNCATED",
+      "message": "Response truncated to fit token budget"
+    }],
+    "_tokenEstimate": {
+      "estimated": 2847,
+      "budget": 4000,
+      "method": "character_based"
+    }
+  }
+}
+```
+
+#### 9.5.3 Error Specification
+
+**E_MVI_BUDGET_EXCEEDED:**
+- **Category:** `VALIDATION`
+- **Retryable:** `true`
+- **Details:** `estimatedTokens`, `budget`, `excessTokens`, `constraint`
+
+```json
+{
+  "error": {
+    "code": "E_MVI_BUDGET_EXCEEDED",
+    "message": "Response exceeds declared token budget",
+    "category": "VALIDATION",
+    "retryable": true,
+    "details": {
+      "estimatedTokens": 5234,
+      "budget": 4000,
+      "excessTokens": 1234,
+      "constraint": "maxTokens"
+    }
+  }
+}
+```
+
+#### 9.5.4 Token Estimation Algorithm (Normative)
+
+Servers MUST implement this algorithm or equivalent (within +/- 10%):
+
+```
+FUNCTION estimate_tokens(value, depth = 0):
+    IF depth > 20: RETURN INFINITY
+    IF value IS null: RETURN 1
+    IF value IS boolean: RETURN 1
+    IF value IS number: RETURN max(1, len(stringify(value)) / 4)
+    IF value IS string:
+        graphemes = count_grapheme_clusters(value)
+        RETURN max(1, graphemes / 4.0)
+    IF value IS array:
+        tokens = 2  // []
+        FOR item IN value:
+            tokens += estimate_tokens(item, depth + 1) + 1
+        RETURN tokens
+    IF value IS object:
+        tokens = 2  // {}
+        FOR key, val IN value:
+            tokens += estimate_tokens(key, depth + 1)
+            tokens += 2  // : and ,
+            tokens += estimate_tokens(val, depth + 1)
+        RETURN tokens
+```
+
+**Requirements:**
+- Count grapheme clusters (not bytes) for unicode
+- Enforce max depth of 20
+- Handle circular references
+- Complete within 10ms for 100KB payloads
+
 ---
 
 ## 10. Strictness

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "0.5.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"
   },
@@ -50,13 +50,19 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@types/express": "^5.0.6",
     "@types/node": "^24.3.0",
+    "@types/supertest": "^6.0.3",
+    "supertest": "^7.2.2",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
     "vitest": "^2.1.9"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1"
+    "@a2a-js/sdk": "^0.3.10",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "express": "^5.2.1"
   }
 }

package/schemas/v1/discovery.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lafs.dev/schemas/v1/discovery.schema.json",
+  "title": "LAFS Discovery Document",
+  "description": "Schema for LAFS agent discovery documents served at /.well-known/lafs.json",
+  "type": "object",
+  "required": [
+    "$schema",
+    "lafs_version",
+    "service",
+    "capabilities",
+    "endpoints"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the schema this document conforms to"
+    },
+    "lafs_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "LAFS protocol version (semantic versioning)"
+    },
+    "service": {
+      "type": "object",
+      "description": "Service identification and metadata",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Unique service name (kebab-case recommended)"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Service version (semantic versioning)"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Human-readable service description"
+        }
+      },
+      "additionalProperties": false
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "List of LAFS capabilities this service provides",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "version",
+          "operations"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "description": "Capability identifier (kebab-case recommended)"
+          },
+          "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+$",
+            "description": "Capability version (semantic versioning)"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Human-readable capability description"
+          },
+          "operations": {
+            "type": "array",
+            "description": "List of operations this capability supports",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 50
+            }
+          },
+          "optional": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether this capability is optional for clients"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "endpoints": {
+      "type": "object",
+      "description": "URL endpoints for LAFS operations",
+      "required": [
+        "envelope",
+        "discovery"
+      ],
+      "properties": {
+        "envelope": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL for envelope submission (POST)"
+        },
+        "context": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL for context ledger operations"
+        },
+        "discovery": {
+          "type": "string",
+          "minLength": 1,
+          "description": "URL of this discovery document"
+        }
+      },
+      "additionalProperties": false
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Extension fields for vendor-specific metadata",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}