@cleocode/lafs-protocol 1.4.1 → 1.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 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.4.1 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
+**Current version:** 1.5.0 | [📚 Documentation](https://codluv.gitbook.io/lafs-protocol/) | [Spec](lafs.md) | [Migration Guides](migrations/)
 
 [![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs-protocol/)
 [![npm](https://img.shields.io/npm/v/@cleocode/lafs-protocol)](https://www.npmjs.com/package/@cleocode/lafs-protocol)

package/dist/schemas/v1/error-registry.json

@@ -109,6 +109,15 @@
             "httpStatus": 413,
             "grpcStatus": "RESOURCE_EXHAUSTED",
             "cliExit": 2
+        },
+        {
+            "code": "E_FIELD_CONFLICT",
+            "category": "CONTRACT",
+            "description": "Mutually exclusive field selection modes (single-field extraction and multi-field filtering cannot be combined)",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2
         }
     ]
 }

package/dist/src/conformance.js

@@ -1,5 +1,6 @@
 import { getTransportMapping, isRegisteredErrorCode } from "./errorRegistry.js";
 import { resolveOutputFormat, LAFSFlagError } from "./flagSemantics.js";
+import { isMVILevel } from "./types.js";
 import { getChecksForTier } from "./conformanceProfiles.js";
 import { validateEnvelope } from "./validateEnvelope.js";
 function pushCheck(checks, name, pass, detail) {
@@ -75,8 +76,8 @@ export function runEnvelopeConformance(envelope, options = {}) {
             }
         }
     }
-    const validMviLevels = ["minimal", "standard", "full", "custom"];
-    pushCheck(checks, "meta_mvi_present", validMviLevels.includes(typed._meta.mvi), validMviLevels.includes(typed._meta.mvi) ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
+    const mviValid = isMVILevel(typed._meta.mvi);
+    pushCheck(checks, "meta_mvi_present", mviValid, mviValid ? undefined : `invalid mvi level: ${String(typed._meta.mvi)}`);
     pushCheck(checks, "meta_strict_present", typeof typed._meta.strict === "boolean");
     // strict_mode_behavior: when strict=true, the envelope MUST NOT contain
     // explicit null for optional fields that can be omitted (page, error on success).

package/dist/src/fieldExtraction.d.ts

@@ -0,0 +1,67 @@
+import type { LAFSEnvelope, MVILevel } from "./types.js";
+export interface FieldExtractionInput {
+    /** --field <name>: extract single field as plain text, no envelope */
+    fieldFlag?: string;
+    /** --fields <a,b,c>: filter result to these fields, preserve envelope */
+    fieldsFlag?: string | string[];
+    /** --mvi <level>: envelope verbosity (client-requestable levels only) */
+    mviFlag?: MVILevel | string;
+}
+export interface FieldExtractionResolution {
+    /** When set: extract this field as plain text, discard envelope. */
+    field?: string;
+    /** When set: filter result to these fields (envelope preserved). */
+    fields?: string[];
+    /** Resolved MVI level. Defaults to 'standard'. */
+    mvi: MVILevel;
+    /** Which input determined the mvi value: 'flag' when mviFlag was valid, 'default' otherwise. */
+    mviSource: "flag" | "default";
+    /**
+     * True when _fields are requested, indicating the server SHOULD set
+     * _meta.mvi = 'custom' in the response per §9.1.
+     * Separate from the client-resolved mvi level.
+     */
+    expectsCustomMvi: boolean;
+}
+export declare function resolveFieldExtraction(input: FieldExtractionInput): FieldExtractionResolution;
+/**
+ * Extract a named field from a LAFS result object.
+ *
+ * Handles four result shapes:
+ *   1. Direct array: result[0][field]       (list operations where result IS an array)
+ *   2. Direct:       result[field]          (flat result object)
+ *   3. Nested:       result.<key>[field]    (wrapper-entity, e.g. result.task.title)
+ *   4. Array value:  result.<key>[0][field] (wrapper-array, e.g. result.items[0].title)
+ *
+ * Returns the value from the first match only. For array results (shapes 1
+ * and 4), returns the first element's field value only. To extract from all
+ * elements, iterate the array or use applyFieldFilter().
+ *
+ * When multiple wrapper keys contain the requested field (shapes 3 and 4),
+ * the first key in property insertion order wins.
+ *
+ * Returns undefined if not found at any level.
+ */
+export declare function extractFieldFromResult(result: LAFSEnvelope['result'], field: string): unknown;
+/** Convenience wrapper — extracts a field from an envelope's result. */
+export declare function extractFieldFromEnvelope(envelope: LAFSEnvelope, field: string): unknown;
+/**
+ * Filter result fields in a LAFS envelope to the requested subset.
+ *
+ * Handles the same four result shapes as extractFieldFromResult:
+ *   1. Direct array:    project each element
+ *   2. Flat result:     project top-level keys
+ *   3. Wrapper-entity:  project nested entity's keys, preserve wrapper
+ *   4. Wrapper-array:   project each element's keys, preserve wrapper
+ *
+ * Sets _meta.mvi = 'custom' per §9.1.
+ * Returns a new envelope with a new _meta object. Result values are not
+ * deep-cloned; nested object references are shared with the original.
+ * Unknown field names are silently omitted per §9.2.
+ *
+ * When result is a wrapper (shapes 3/4) with multiple keys, each key is
+ * projected independently. Primitive values at the wrapper level (numbers,
+ * strings, booleans) are preserved as-is — _fields is applied to nested
+ * entity or array keys only, not to the wrapper's own primitive keys.
+ */
+export declare function applyFieldFilter(envelope: LAFSEnvelope, fields: string[]): LAFSEnvelope;

package/dist/src/fieldExtraction.js

@@ -0,0 +1,133 @@
+import { LAFSFlagError } from "./flagSemantics.js";
+import { isMVILevel } from "./types.js";
+export function resolveFieldExtraction(input) {
+    if (input.fieldFlag && input.fieldsFlag) {
+        throw new LAFSFlagError('E_FIELD_CONFLICT', 'Cannot combine --field and --fields: --field extracts a single value '
+            + 'as plain text (no envelope); --fields filters the JSON envelope. '
+            + 'Use one or the other.', { conflictingModes: ['single-field-extraction', 'multi-field-filter'] });
+    }
+    const fields = typeof input.fieldsFlag === 'string'
+        ? input.fieldsFlag.split(',').map(f => f.trim()).filter(Boolean)
+        : Array.isArray(input.fieldsFlag)
+            ? input.fieldsFlag.map(f => f.trim()).filter(Boolean)
+            : undefined;
+    // 'custom' is server-set (§9.1) — not a client-requestable level
+    const validMvi = isMVILevel(input.mviFlag) && input.mviFlag !== 'custom';
+    const mvi = validMvi ? input.mviFlag : 'standard';
+    const mviSource = validMvi ? 'flag' : 'default';
+    const hasFields = (fields?.length ?? 0) > 0;
+    return {
+        field: input.fieldFlag || undefined,
+        fields: hasFields ? fields : undefined,
+        mvi,
+        mviSource,
+        expectsCustomMvi: hasFields,
+    };
+}
+/**
+ * Extract a named field from a LAFS result object.
+ *
+ * Handles four result shapes:
+ *   1. Direct array: result[0][field]       (list operations where result IS an array)
+ *   2. Direct:       result[field]          (flat result object)
+ *   3. Nested:       result.<key>[field]    (wrapper-entity, e.g. result.task.title)
+ *   4. Array value:  result.<key>[0][field] (wrapper-array, e.g. result.items[0].title)
+ *
+ * Returns the value from the first match only. For array results (shapes 1
+ * and 4), returns the first element's field value only. To extract from all
+ * elements, iterate the array or use applyFieldFilter().
+ *
+ * When multiple wrapper keys contain the requested field (shapes 3 and 4),
+ * the first key in property insertion order wins.
+ *
+ * Returns undefined if not found at any level.
+ */
+export function extractFieldFromResult(result, field) {
+    if (result === null || typeof result !== 'object')
+        return undefined;
+    // Shape 1: result is a direct array
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return undefined;
+        const first = result[0];
+        if (first && typeof first === 'object' && field in first)
+            return first[field];
+        return undefined;
+    }
+    // Shape 2: direct property on result object
+    const record = result;
+    if (field in record)
+        return record[field];
+    // Shapes 3 & 4: one level down (first matching key in insertion order wins)
+    for (const value of Object.values(record)) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const nested = value;
+            if (field in nested)
+                return nested[field];
+        }
+        if (Array.isArray(value) && value.length > 0) {
+            const first = value[0];
+            if (first && typeof first === 'object' && field in first)
+                return first[field];
+        }
+    }
+    return undefined;
+}
+/** Convenience wrapper — extracts a field from an envelope's result. */
+export function extractFieldFromEnvelope(envelope, field) {
+    return extractFieldFromResult(envelope.result, field);
+}
+/**
+ * Filter result fields in a LAFS envelope to the requested subset.
+ *
+ * Handles the same four result shapes as extractFieldFromResult:
+ *   1. Direct array:    project each element
+ *   2. Flat result:     project top-level keys
+ *   3. Wrapper-entity:  project nested entity's keys, preserve wrapper
+ *   4. Wrapper-array:   project each element's keys, preserve wrapper
+ *
+ * Sets _meta.mvi = 'custom' per §9.1.
+ * Returns a new envelope with a new _meta object. Result values are not
+ * deep-cloned; nested object references are shared with the original.
+ * Unknown field names are silently omitted per §9.2.
+ *
+ * When result is a wrapper (shapes 3/4) with multiple keys, each key is
+ * projected independently. Primitive values at the wrapper level (numbers,
+ * strings, booleans) are preserved as-is — _fields is applied to nested
+ * entity or array keys only, not to the wrapper's own primitive keys.
+ */
+export function applyFieldFilter(envelope, fields) {
+    if (fields.length === 0 || envelope.result === null)
+        return envelope;
+    const pick = (obj) => Object.fromEntries(fields.filter(f => f in obj).map(f => [f, obj[f]]));
+    let filtered;
+    if (Array.isArray(envelope.result)) {
+        // Shape 1: direct array
+        filtered = envelope.result.map(pick);
+    }
+    else {
+        const record = envelope.result;
+        const topLevelMatch = fields.some(f => f in record);
+        if (topLevelMatch) {
+            // Shape 2: flat result
+            filtered = pick(record);
+        }
+        else {
+            // Shapes 3 & 4: wrapper — apply pick one level down, preserve wrapper keys
+            filtered = Object.fromEntries(Object.entries(record).map(([k, v]) => {
+                if (Array.isArray(v)) {
+                    return [k, v.map(item => pick(item))];
+                }
+                if (v && typeof v === 'object') {
+                    return [k, pick(v)];
+                }
+                return [k, v];
+            }));
+        }
+    }
+    return {
+        ...envelope,
+        _meta: { ...envelope._meta, mvi: 'custom' },
+        result: filtered,
+    };
+}

package/dist/src/flagSemantics.d.ts

@@ -1,12 +1,16 @@
-import type { FlagInput } from "./types.js";
+import type { FlagInput, LAFSError, LAFSErrorCategory } 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 {
+export declare class LAFSFlagError extends Error implements LAFSError {
     code: string;
-    constructor(code: string, message: string);
+    category: LAFSErrorCategory;
+    retryable: boolean;
+    retryAfterMs: number | null;
+    details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 export declare function resolveOutputFormat(input: FlagInput): FlagResolution;

package/dist/src/flagSemantics.js

@@ -1,9 +1,19 @@
+import { getRegistryCode } from "./errorRegistry.js";
 export class LAFSFlagError extends Error {
     code;
-    constructor(code, message) {
+    category;
+    retryable;
+    retryAfterMs;
+    details;
+    constructor(code, message, details = {}) {
         super(message);
         this.name = "LAFSFlagError";
         this.code = code;
+        const entry = getRegistryCode(code);
+        this.category = (entry?.category ?? "CONTRACT");
+        this.retryable = entry?.retryable ?? false;
+        this.retryAfterMs = null;
+        this.details = details;
     }
 }
 export function resolveOutputFormat(input) {

package/dist/src/index.d.ts

@@ -4,6 +4,7 @@ export * from "./deprecationRegistry.js";
 export * from "./validateEnvelope.js";
 export * from "./envelope.js";
 export * from "./flagSemantics.js";
+export * from "./fieldExtraction.js";
 export * from "./conformance.js";
 export * from "./conformanceProfiles.js";
 export * from "./compliance.js";

package/dist/src/index.js

@@ -4,6 +4,7 @@ export * from "./deprecationRegistry.js";
 export * from "./validateEnvelope.js";
 export * from "./envelope.js";
 export * from "./flagSemantics.js";
+export * from "./fieldExtraction.js";
 export * from "./conformance.js";
 export * from "./conformanceProfiles.js";
 export * from "./compliance.js";

package/dist/src/types.d.ts

@@ -8,6 +8,8 @@ export interface Warning {
     removeBy?: string;
 }
 export type MVILevel = 'minimal' | 'standard' | 'full' | 'custom';
+export declare const MVI_LEVELS: ReadonlySet<MVILevel>;
+export declare function isMVILevel(value: unknown): value is MVILevel;
 export interface LAFSMeta {
     specVersion: string;
     schemaVersion: string;

package/dist/src/types.js

@@ -1 +1,6 @@
-export {};
+export const MVI_LEVELS = new Set([
+    'minimal', 'standard', 'full', 'custom',
+]);
+export function isMVILevel(value) {
+    return typeof value === 'string' && MVI_LEVELS.has(value);
+}

package/lafs.md

@@ -1,7 +1,7 @@
 # LAFS: LLM-Agent-First Specification
 
 > 📚 **Documentation:** https://codluv.gitbook.io/lafs-protocol/  
-> **Version:** 1.4.1 | **Status:** Production Ready
+> **Version:** 1.5.0 | **Status:** Production Ready
 
 ## 1. Scope
 
@@ -431,16 +431,45 @@ To reduce token and I/O overhead, implementations SHOULD support lazy retrieval
 - Default list/batch outputs MUST only contain fields required for next action.
 - Verbose fields SHOULD be omitted by default.
 - Systems SHOULD publish operation-level MVI budgets.
+- `_meta.mvi` MUST be one of: `minimal`, `standard`, `full`, or `custom`.
+- `_meta` is a structural envelope field and MUST always be present regardless
+  of `mvi` level. MVI levels govern the contents of `result` only; they MUST NOT
+  affect envelope structural fields (`$schema`, `_meta`, `success`, `error`,
+  `page`, `_extensions`).
+- `minimal`: MUST include only fields within `result` sufficient for the next
+  agent action (typically identifiers and status). Implementations SHOULD
+  document which fields constitute `minimal` per operation.
+- `standard` (default): MUST include all commonly useful fields for the
+  operation.
+- `full`: MUST include all available fields including verbose and
+  rarely-accessed data.
+- `custom`: MUST be set by the server when `_fields` projection has been
+  applied, indicating the result does not conform to any predefined disclosure
+  level. `custom` is not a client-requestable level.
 
 ### 9.2 Field selection (`_fields`)
 
-Clients MAY request a subset of response fields via the `_fields` request parameter.
-
-- `_fields` MUST be an array of strings identifying top-level result field names.
-- When `_fields` is present, the server MUST return only the requested fields plus any MVI-required fields for the declared disclosure level.
-- When `_fields` is absent, the server MUST return fields appropriate for the declared `_meta.mvi` disclosure level.
-- If a requested field does not exist on the resource, the server SHOULD omit it silently (no error). Servers MAY include a warning in `_meta.warnings` for unknown fields.
-- `_fields` MUST NOT affect envelope structural fields (`$schema`, `_meta`, `success`, `error`, `page`, `_extensions`); it applies only to the contents of `result`.
+Clients MAY request a subset of response fields via the `_fields` request
+parameter.
+
+- `_fields` MUST be an array of strings identifying `result` field names.
+  Path notation (e.g., `task.title`) is not defined by this specification.
+- When `result` is an array, `_fields` applies to the keys of each element.
+- When `result` is a wrapper object whose values are entities or arrays of
+  entities (e.g., `{ "task": { ... } }` or `{ "items": [...] }`), servers
+  SHOULD apply `_fields` to the nested entity fields rather than the wrapper's
+  own keys.
+- When `_fields` is present, the server MUST return only the requested fields
+  plus any MVI-required fields for the declared disclosure level.
+  The server MUST set `_meta.mvi` to `custom` in the response.
+- When `_fields` is absent, the server MUST return fields appropriate for the
+  declared `_meta.mvi` disclosure level.
+- If a requested field does not exist on the resource, the server SHOULD omit
+  it silently (no error). Servers MAY include a warning in `_meta.warnings`
+  for unknown fields.
+- `_fields` MUST NOT affect envelope structural fields (`$schema`, `_meta`,
+  `success`, `error`, `page`, `_extensions`); it applies only to the contents
+  of `result`.
 
 ### 9.3 Expansion mechanism (`_expand`)
 

package/package.json

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

package/schemas/v1/error-registry.json

@@ -109,6 +109,15 @@
       "httpStatus": 413,
       "grpcStatus": "RESOURCE_EXHAUSTED",
       "cliExit": 2
+    },
+    {
+      "code": "E_FIELD_CONFLICT",
+      "category": "CONTRACT",
+      "description": "Mutually exclusive field selection modes (single-field extraction and multi-field filtering cannot be combined)",
+      "retryable": false,
+      "httpStatus": 400,
+      "grpcStatus": "INVALID_ARGUMENT",
+      "cliExit": 2
     }
   ]
 }