@cleocode/lafs-protocol 1.1.0 → 1.2.0

package/dist/schemas/v1/envelope.schema.json

@@ -67,6 +67,12 @@
                     "type": "integer",
                     "minimum": 0
                 },
+                "sessionId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 256,
+                    "description": "Session identifier for correlating multi-step agent workflows"
+                },
                 "warnings": {
                     "type": "array",
                     "items": {

package/dist/src/flagSemantics.d.ts

@@ -2,6 +2,8 @@ import type { FlagInput } from "./types.js";
 export interface FlagResolution {
     format: "json" | "human";
     source: "flag" | "project" | "user" | "default";
+    /** When true, suppress non-essential output for scripting */
+    quiet: boolean;
 }
 export declare class LAFSFlagError extends Error {
     code: string;

package/dist/src/flagSemantics.js

@@ -10,20 +10,21 @@ export function resolveOutputFormat(input) {
     if (input.humanFlag && input.jsonFlag) {
         throw new LAFSFlagError("E_FORMAT_CONFLICT", "Cannot combine --human and --json in the same invocation.");
     }
+    const quiet = input.quiet ?? false;
     if (input.requestedFormat) {
-        return { format: input.requestedFormat, source: "flag" };
+        return { format: input.requestedFormat, source: "flag", quiet };
     }
     if (input.humanFlag) {
-        return { format: "human", source: "flag" };
+        return { format: "human", source: "flag", quiet };
     }
     if (input.jsonFlag) {
-        return { format: "json", source: "flag" };
+        return { format: "json", source: "flag", quiet };
     }
     if (input.projectDefault) {
-        return { format: input.projectDefault, source: "project" };
+        return { format: input.projectDefault, source: "project", quiet };
     }
     if (input.userDefault) {
-        return { format: input.userDefault, source: "user" };
+        return { format: input.userDefault, source: "user", quiet };
     }
-    return { format: "json", source: "default" };
+    return { format: "json", source: "default", quiet };
 }

package/dist/src/types.d.ts

@@ -17,6 +17,8 @@ export interface LAFSMeta {
     strict: boolean;
     mvi: 'minimal' | 'standard' | 'full' | 'custom';
     contextVersion: number;
+    /** Session identifier for correlating multi-step agent workflows */
+    sessionId?: string;
     warnings?: Warning[];
 }
 export interface LAFSError {
@@ -76,6 +78,8 @@ export interface FlagInput {
     humanFlag?: boolean;
     projectDefault?: "json" | "human";
     userDefault?: "json" | "human";
+    /** Suppress non-essential output for scripting. When true, only essential data is returned. */
+    quiet?: boolean;
 }
 export interface ConformanceReport {
     ok: boolean;

package/lafs.md

@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.0.0 | **Status:** Production Ready
+> **Version:** 1.2.0 | **Status:** Production Ready
 
 ## 1. Scope
 
@@ -67,6 +67,52 @@ The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted per RFC
 3. Global/user config
 4. Protocol default (`json`)
 
+### 5.3 Supported formats
+
+LAFS supports exactly two output formats:
+
+- **`json`** (default) — Machine-readable JSON envelope for programmatic consumption
+- **`human`** — Human-readable text output for terminal display
+
+#### 5.3.1 Human format definition
+
+The `human` format produces plain text output optimized for terminal display:
+
+- Suitable for direct human consumption in CLI environments
+- NOT markdown, NOT tables, NOT structured data
+- May include ANSI colors (respect `NO_COLOR` environment variable)
+- Example: Tabular data displayed with aligned columns using spaces
+
+```
+ID    Name          Status
+----  ------------  --------
+123   Alpha         active
+456   Beta          pending
+```
+
+#### 5.3.2 Rejected formats
+
+The following formats were explicitly rejected to maintain protocol minimalism:
+
+| Format | Status | Rationale |
+|--------|--------|-----------|
+| `text` | ❌ Rejected | Ambiguous overlap with `human`. Use `human` format with `NO_COLOR=1` for plain text. |
+| `markdown` | ❌ Rejected | Presentation format, not data format. Generate from JSON if markdown rendering is needed. |
+| `table` | ❌ Rejected | Presentation concern. Use `jq` + `column` command or `human` format for tabular display. |
+| `jsonl` | ❌ Rejected | Streaming format violates LAFS discrete envelope contract (see Section 2: Non-Goals). |
+
+**Design principle:** LAFS is a response envelope contract, not a presentation layer. Six formats = format proliferation = protocol bloat.
+
+#### 5.3.3 Achieving presentation goals with json format
+
+Consumers needing presentation formats should:
+
+1. Request `json` format from LAFS-compliant services
+2. Transform JSON to desired presentation format using standard tools:
+   - **Markdown:** `jq` + template engine
+   - **Tables:** `jq` + `column` command
+   - **Plain text:** `jq` with `-r` (raw) output
+
 ---
 
 ## 6. Canonical Response Envelope
@@ -110,6 +156,144 @@ The envelope supports an optional `_extensions` object for vendor-specific metad
 - Consumers MUST NOT rely on extension fields for protocol-required behavior.
 - Producers MAY omit `_extensions` entirely; the field is always optional.
 
+#### 6.2.1 Extension use cases
+
+The following examples demonstrate common use cases for `_extensions`. These fields were rejected from the core protocol but are valid extension use cases.
+
+**Example 1: Performance timing**
+
+```typescript
+// Extension type definition
+interface XTimingExtension {
+  "x-timing": {
+    executionMs: number;        // Total request execution time
+    parseMs?: number;           // Input parsing time
+    queryMs?: number;           // Database query time
+    serializeMs?: number;       // Response serialization time
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-timing": {
+      "executionMs": 42,
+      "queryMs": 15,
+      "serializeMs": 3
+    }
+  }
+}
+```
+
+**Example 2: Source metadata**
+
+```typescript
+interface XSourceExtension {
+  "x-source": {
+    gitRef?: string;           // Git commit SHA
+    apiVersion?: string;       // API implementation version
+    buildTimestamp?: string;   // ISO 8601 build time
+    deployment?: string;       // Deployment environment (staging, prod)
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-source": {
+      "gitRef": "abc123def456",
+      "apiVersion": "2.1.0",
+      "deployment": "production"
+    }
+  }
+}
+```
+
+**Example 3: Applied filters**
+
+```typescript
+interface XFiltersExtension {
+  "x-filters": {
+    applied: Array<{
+      field: string;
+      operator: "eq" | "neq" | "gt" | "lt" | "contains";
+      value: unknown;
+    }>;
+    omitted: string[];         // Fields excluded due to permissions
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-filters": {
+      "applied": [
+        { "field": "status", "operator": "eq", "value": "active" },
+        { "field": "createdAt", "operator": "gt", "value": "2024-01-01" }
+      ],
+      "omitted": ["internalNotes", "costCenter"]
+    }
+  }
+}
+```
+
+**Example 4: Result summary**
+
+```typescript
+interface XSummaryExtension {
+  "x-summary": {
+    totalCount: number;        // Total matching records
+    returnedCount: number;     // Records in this response
+    aggregated?: {
+      revenue?: number;
+      count?: number;
+      average?: number;
+    };
+  };
+}
+```
+
+```json
+{
+  "_extensions": {
+    "x-summary": {
+      "totalCount": 150,
+      "returnedCount": 25,
+      "aggregated": {
+        "revenue": 125000.00,
+        "average": 833.33
+      }
+    }
+  }
+}
+```
+
+#### 6.2.2 Extension best practices
+
+1. **Use x- prefix** — All extension keys MUST start with `x-` (e.g., `x-caamp-timing`)
+2. **Document your schema** — Publish extension schemas separately from LAFS core
+3. **Don't rely on extensions for core behavior** — Extensions are informational only
+4. **Version your extensions** — Include version in extension key if schema may change (e.g., `x-vendor-v2-field`)
+5. **Keep extensions optional** — Consumers MUST be able to operate without extension data
+6. **Namespace by vendor** — Use vendor prefix to avoid collisions (e.g., `x-caamp-`, `x-acme-`)
+
+#### 6.2.3 When to use extensions vs core protocol
+
+| Use Case | Core Protocol | Extensions |
+|----------|---------------|------------|
+| Session correlation | ✅ sessionId | — |
+| Soft warnings | ✅ warnings array | — |
+| Performance timing | — | ✅ x-timing |
+| Source/version metadata | — | ✅ x-source |
+| Debug filters | — | ✅ x-filters |
+| Derived summaries | — | ✅ x-summary |
+| Data integrity (TLS covers) | — | ✅ x-checksum (if needed) |
+
+**Guideline:** If a field is required for basic operation, it belongs in core. If it's useful for debugging, monitoring, or rich display, it belongs in extensions.
+
 ---
 
 ## 7. Error Contract

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/lafs-protocol",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "description": "LLM-Agent-First Specification schemas and conformance tooling",

package/schemas/v1/envelope.schema.json

@@ -67,6 +67,12 @@
           "type": "integer",
           "minimum": 0
         },
+        "sessionId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Session identifier for correlating multi-step agent workflows"
+        },
         "warnings": {
           "type": "array",
           "items": {