@cleocode/lafs 1.8.0

package/dist/src/tokenEstimator.js

@@ -0,0 +1,238 @@
+/**
+ * LAFS Token Estimator
+ *
+ * Provides character-based token estimation for LAFS envelopes and JSON payloads.
+ * Uses the approximation: 1 token ≈ 4 characters.
+ * Properly handles nested objects, arrays, Unicode graphemes, and circular references.
+ */
+/**
+ * Counts Unicode graphemes in a string using Intl.Segmenter when available.
+ * Falls back to character counting for environments without Intl.Segmenter.
+ */
+function countGraphemes(str) {
+    // Use Intl.Segmenter for proper grapheme counting (Node.js 16+, modern browsers)
+    if (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {
+        // @ts-ignore - Intl.Segmenter may not be in all TypeScript lib versions
+        const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+        // @ts-ignore
+        return Array.from(segmenter.segment(str)).length;
+    }
+    // Fallback: count code points using spread operator (handles surrogate pairs)
+    return [...str].length;
+}
+/**
+ * Default options for token estimation
+ */
+const DEFAULT_OPTIONS = {
+    charsPerToken: 4,
+    maxDepth: 100,
+    maxStringLength: 100000,
+};
+/**
+ * TokenEstimator provides character-based token counting for JSON payloads.
+ *
+ * Algorithm:
+ * 1. Serialize value to JSON (handling circular refs)
+ * 2. Count Unicode graphemes (not bytes)
+ * 3. Divide by charsPerToken ratio (default 4)
+ * 4. Add overhead for structural characters
+ */
+export class TokenEstimator {
+    options;
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Estimate tokens for any JavaScript value.
+     * Handles circular references, nested objects, arrays, and Unicode.
+     *
+     * @param value - Any value to estimate
+     * @returns Estimated token count
+     */
+    estimate(value) {
+        return this.estimateWithTracking(value, new WeakSet(), 0);
+    }
+    /**
+     * Estimate tokens from a JSON string.
+     * More efficient if you already have the JSON string.
+     *
+     * @param json - JSON string to estimate
+     * @returns Estimated token count
+     */
+    estimateJSON(json) {
+        // Count graphemes in the JSON string
+        const graphemes = countGraphemes(json);
+        // Add overhead for JSON structure (brackets, quotes, colons, etc.)
+        const structuralOverhead = Math.ceil(graphemes * 0.1);
+        return Math.ceil((graphemes + structuralOverhead) / this.options.charsPerToken);
+    }
+    /**
+     * Internal recursive estimation with circular reference tracking.
+     */
+    estimateWithTracking(value, seen, depth) {
+        // Prevent infinite recursion
+        if (depth > this.options.maxDepth) {
+            return 1; // Minimal cost for max depth exceeded
+        }
+        // Handle null
+        if (value === null) {
+            return 1; // "null" = 4 chars / 4 = 1 token
+        }
+        // Handle undefined
+        if (value === undefined) {
+            return 1;
+        }
+        // Handle primitives
+        const type = typeof value;
+        if (type === 'boolean') {
+            return value ? 1 : 1; // "true" or "false" ≈ 1 token
+        }
+        if (type === 'number') {
+            const str = String(value);
+            return Math.ceil(countGraphemes(str) / this.options.charsPerToken);
+        }
+        if (type === 'string') {
+            const str = value;
+            // Limit string length to prevent performance issues
+            const truncated = str.length > this.options.maxStringLength
+                ? str.slice(0, this.options.maxStringLength) + '…'
+                : str;
+            const graphemes = countGraphemes(truncated);
+            // Add 2 for quotes
+            return Math.ceil((graphemes + 2) / this.options.charsPerToken);
+        }
+        // Handle objects and arrays
+        if (type === 'object') {
+            const obj = value;
+            // Check for circular reference
+            if (seen.has(obj)) {
+                return 1; // Minimal cost for circular ref placeholder
+            }
+            seen.add(obj);
+            try {
+                if (Array.isArray(obj)) {
+                    return this.estimateArray(obj, seen, depth);
+                }
+                return this.estimateObject(obj, seen, depth);
+            }
+            finally {
+                seen.delete(obj);
+            }
+        }
+        // Handle symbols, functions, etc.
+        return 1;
+    }
+    /**
+     * Estimate tokens for an array.
+     */
+    estimateArray(arr, seen, depth) {
+        let tokens = 1; // Opening bracket [ (already counted as structural)
+        for (let i = 0; i < arr.length; i++) {
+            tokens += this.estimateWithTracking(arr[i], seen, depth + 1);
+            // Add comma separator (except for last element)
+            if (i < arr.length - 1) {
+                tokens += 1; // comma + space ≈ 2 chars / 4 = 0.5, round up to 1
+            }
+        }
+        tokens += 1; // Closing bracket ]
+        return tokens;
+    }
+    /**
+     * Estimate tokens for a plain object.
+     */
+    estimateObject(obj, seen, depth) {
+        let tokens = 1; // Opening brace {
+        const keys = Object.keys(obj);
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const value = obj[key];
+            // Estimate key (with quotes)
+            tokens += Math.ceil((countGraphemes(key) + 2) / this.options.charsPerToken);
+            // Colon separator
+            tokens += 1; // " : " ≈ 3 chars / 4 = 0.75, round up to 1
+            // Estimate value
+            tokens += this.estimateWithTracking(value, seen, depth + 1);
+            // Comma separator (except for last property)
+            if (i < keys.length - 1) {
+                tokens += 1; // comma + space ≈ 2 chars / 4 = 0.5, round up to 1
+            }
+        }
+        tokens += 1; // Closing brace }
+        return tokens;
+    }
+    /**
+     * Check if a value can be safely serialized (no circular refs).
+     */
+    canSerialize(value) {
+        try {
+            JSON.stringify(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Serialize value to JSON with circular reference handling.
+     * Circular refs are replaced with "[Circular]".
+     */
+    safeStringify(value) {
+        const seen = new WeakSet();
+        return JSON.stringify(value, (key, val) => {
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return '[Circular]';
+                }
+                seen.add(val);
+            }
+            return val;
+        });
+    }
+    /**
+     * Create a safe copy of a value with circular refs removed.
+     */
+    safeCopy(value) {
+        const seen = new WeakSet();
+        function clone(val) {
+            if (val === null || typeof val !== 'object') {
+                return val;
+            }
+            if (seen.has(val)) {
+                return '[Circular]';
+            }
+            seen.add(val);
+            try {
+                if (Array.isArray(val)) {
+                    return val.map(clone);
+                }
+                const result = {};
+                for (const [k, v] of Object.entries(val)) {
+                    result[k] = clone(v);
+                }
+                return result;
+            }
+            finally {
+                seen.delete(val);
+            }
+        }
+        return clone(value);
+    }
+}
+/**
+ * Global token estimator instance with default settings.
+ */
+export const defaultEstimator = new TokenEstimator();
+/**
+ * Convenience function to estimate tokens for a value.
+ */
+export function estimateTokens(value, options) {
+    const estimator = options ? new TokenEstimator(options) : defaultEstimator;
+    return estimator.estimate(value);
+}
+/**
+ * Convenience function to estimate tokens from a JSON string.
+ */
+export function estimateTokensJSON(json, options) {
+    const estimator = options ? new TokenEstimator(options) : defaultEstimator;
+    return estimator.estimateJSON(json);
+}

package/dist/src/types.d.ts

@@ -0,0 +1,135 @@
+export type LAFSTransport = "cli" | "http" | "grpc" | "sdk";
+export type LAFSErrorCategory = "VALIDATION" | "AUTH" | "PERMISSION" | "NOT_FOUND" | "CONFLICT" | "RATE_LIMIT" | "TRANSIENT" | "INTERNAL" | "CONTRACT" | "MIGRATION";
+export interface Warning {
+    code: string;
+    message: string;
+    deprecated?: string;
+    replacement?: string;
+    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;
+    timestamp: string;
+    operation: string;
+    requestId: string;
+    transport: LAFSTransport;
+    strict: boolean;
+    mvi: MVILevel;
+    contextVersion: number;
+    /** Session identifier for correlating multi-step agent workflows */
+    sessionId?: string;
+    warnings?: Warning[];
+}
+export type LAFSAgentAction = 'retry' | 'retry_modified' | 'escalate' | 'stop' | 'wait' | 'refresh_context' | 'authenticate';
+export declare const AGENT_ACTIONS: ReadonlySet<LAFSAgentAction>;
+export declare function isAgentAction(value: unknown): value is LAFSAgentAction;
+export interface LAFSError {
+    code: string;
+    message: string;
+    category: LAFSErrorCategory;
+    retryable: boolean;
+    retryAfterMs: number | null;
+    details: Record<string, unknown>;
+    agentAction?: LAFSAgentAction;
+    escalationRequired?: boolean;
+    suggestedAction?: string;
+    docUrl?: string;
+}
+export interface LAFSPageCursor {
+    mode: "cursor";
+    nextCursor: string | null;
+    hasMore: boolean;
+    limit?: number;
+    total?: number | null;
+}
+export interface LAFSPageOffset {
+    mode: "offset";
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    total?: number | null;
+}
+export interface LAFSPageNone {
+    mode: "none";
+}
+export type LAFSPage = LAFSPageCursor | LAFSPageOffset | LAFSPageNone;
+export interface ContextLedgerEntry {
+    entryId: string;
+    timestamp: string;
+    operation: string;
+    contextDelta: Record<string, unknown>;
+    requestId?: string;
+}
+export interface ContextLedger {
+    ledgerId: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    entries: ContextLedgerEntry[];
+    checksum: string;
+    maxEntries: number;
+}
+export interface LAFSEnvelope {
+    $schema: "https://lafs.dev/schemas/v1/envelope.schema.json";
+    _meta: LAFSMeta;
+    success: boolean;
+    result: Record<string, unknown> | Record<string, unknown>[] | null;
+    error?: LAFSError | null;
+    page?: LAFSPage | null;
+    _extensions?: Record<string, unknown>;
+}
+export interface FlagInput {
+    requestedFormat?: "json" | "human";
+    jsonFlag?: boolean;
+    humanFlag?: boolean;
+    projectDefault?: "json" | "human";
+    userDefault?: "json" | "human";
+    /**
+     * When true, indicates the output is connected to an interactive terminal.
+     * If no explicit format flag or project/user default is set, TTY terminals
+     * default to `"human"` format while non-TTY (piped, CI, agents) defaults
+     * to `"json"` per the LAFS protocol.
+     *
+     * CLI tools should pass `process.stdout.isTTY ?? false` here.
+     */
+    tty?: boolean;
+    /** Suppress non-essential output for scripting. When true, only essential data is returned. */
+    quiet?: boolean;
+}
+export interface ConformanceReport {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        pass: boolean;
+        detail?: string;
+    }>;
+}
+export type BudgetEnforcementOptions = {
+    truncateOnExceed?: boolean;
+    onBudgetExceeded?: (estimated: number, budget: number) => void;
+};
+export interface TokenEstimate {
+    estimated: number;
+    truncated?: boolean;
+    originalEstimate?: number;
+}
+export interface LAFSMetaWithBudget extends LAFSMeta {
+    _tokenEstimate?: TokenEstimate;
+}
+export interface LAFSEnvelopeWithBudget extends Omit<LAFSEnvelope, '_meta'> {
+    _meta: LAFSMetaWithBudget;
+}
+export type MiddlewareFunction = (envelope: LAFSEnvelope) => LAFSEnvelope | Promise<LAFSEnvelope>;
+export type NextFunction = () => LAFSEnvelope | Promise<LAFSEnvelope>;
+export type BudgetMiddleware = (envelope: LAFSEnvelope, next: NextFunction) => Promise<LAFSEnvelope> | LAFSEnvelope;
+export interface BudgetEnforcementResult {
+    envelope: LAFSEnvelope;
+    withinBudget: boolean;
+    estimatedTokens: number;
+    budget: number;
+    truncated: boolean;
+}

package/dist/src/types.js

@@ -0,0 +1,12 @@
+export const MVI_LEVELS = new Set([
+    'minimal', 'standard', 'full', 'custom',
+]);
+export function isMVILevel(value) {
+    return typeof value === 'string' && MVI_LEVELS.has(value);
+}
+export const AGENT_ACTIONS = new Set([
+    'retry', 'retry_modified', 'escalate', 'stop', 'wait', 'refresh_context', 'authenticate',
+]);
+export function isAgentAction(value) {
+    return typeof value === 'string' && AGENT_ACTIONS.has(value);
+}

package/dist/src/validateEnvelope.d.ts

@@ -0,0 +1,15 @@
+import type { LAFSEnvelope } from "./types.js";
+/** Structured representation of a single validation error from AJV */
+export interface StructuredValidationError {
+    path: string;
+    keyword: string;
+    message: string;
+    params: Record<string, unknown>;
+}
+export interface EnvelopeValidationResult {
+    valid: boolean;
+    errors: string[];
+    structuredErrors: StructuredValidationError[];
+}
+export declare function validateEnvelope(input: unknown): EnvelopeValidationResult;
+export declare function assertEnvelope(input: unknown): LAFSEnvelope;

package/dist/src/validateEnvelope.js

@@ -0,0 +1,31 @@
+import { createRequire } from "node:module";
+import envelopeSchema from "../schemas/v1/envelope.schema.json" with { type: "json" };
+const require = createRequire(import.meta.url);
+const AjvModule = require("ajv");
+const AddFormatsModule = require("ajv-formats");
+const AjvCtor = (typeof AjvModule === "function" ? AjvModule : AjvModule.default);
+const addFormats = (typeof AddFormatsModule === "function" ? AddFormatsModule : AddFormatsModule.default);
+const ajv = new AjvCtor({ allErrors: true, strict: true, allowUnionTypes: true });
+addFormats(ajv);
+const validate = ajv.compile(envelopeSchema);
+export function validateEnvelope(input) {
+    const valid = validate(input);
+    if (valid) {
+        return { valid: true, errors: [], structuredErrors: [] };
+    }
+    const structuredErrors = (validate.errors ?? []).map((error) => ({
+        path: error.instancePath || "/",
+        keyword: error.keyword ?? "unknown",
+        message: error.message ?? "validation error",
+        params: error.params ?? {},
+    }));
+    const errors = structuredErrors.map((se) => `${se.path} ${se.message}`.trim());
+    return { valid: false, errors, structuredErrors };
+}
+export function assertEnvelope(input) {
+    const result = validateEnvelope(input);
+    if (!result.valid) {
+        throw new Error(`Invalid LAFS envelope: ${result.errors.join("; ")}`);
+    }
+    return input;
+}