@cleocode/lafs-protocol 0.5.0 → 1.1.0

package/dist/examples/mcp-lafs-server.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * MCP-LAFS Server Example
+ *
+ * A working MCP server that wraps all tool responses in LAFS-compliant envelopes.
+ * Demonstrates how LAFS complements MCP by adding structured metadata and budget enforcement.
+ *
+ * Usage: npx ts-node examples/mcp-lafs-server.ts
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { wrapMCPResult } from "../src/mcpAdapter.js";
+const simulatedDatabase = new Map([
+    ["1", { id: "1", name: "Product A", value: 100, createdAt: new Date().toISOString() }],
+    ["2", { id: "2", name: "Product B", value: 200, createdAt: new Date().toISOString() }],
+    ["3", { id: "3", name: "Product C", value: 300, createdAt: new Date().toISOString() }],
+]);
+// Tool definitions
+const TOOLS = [
+    {
+        name: "weather",
+        description: "Get current weather for a location",
+        inputSchema: {
+            type: "object",
+            properties: {
+                location: {
+                    type: "string",
+                    description: "City name or coordinates",
+                },
+                units: {
+                    type: "string",
+                    enum: ["celsius", "fahrenheit"],
+                    description: "Temperature units",
+                    default: "celsius",
+                },
+                _budget: {
+                    type: "number",
+                    description: "Token budget for response (LAFS extension)",
+                    minimum: 10,
+                    maximum: 10000,
+                },
+            },
+            required: ["location"],
+        },
+    },
+    {
+        name: "calculator",
+        description: "Perform mathematical calculations",
+        inputSchema: {
+            type: "object",
+            properties: {
+                operation: {
+                    type: "string",
+                    enum: ["add", "subtract", "multiply", "divide", "power", "sqrt"],
+                    description: "Mathematical operation to perform",
+                },
+                a: {
+                    type: "number",
+                    description: "First operand",
+                },
+                b: {
+                    type: "number",
+                    description: "Second operand (not needed for sqrt)",
+                },
+                _budget: {
+                    type: "number",
+                    description: "Token budget for response (LAFS extension)",
+                    minimum: 10,
+                    maximum: 1000,
+                },
+            },
+            required: ["operation", "a"],
+        },
+    },
+    {
+        name: "database_query",
+        description: "Query the simulated database",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["get", "list", "search"],
+                    description: "Query action to perform",
+                },
+                id: {
+                    type: "string",
+                    description: "Record ID (for get action)",
+                },
+                query: {
+                    type: "string",
+                    description: "Search query (for search action)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum results to return",
+                    default: 10,
+                },
+                _budget: {
+                    type: "number",
+                    description: "Token budget for response (LAFS extension)",
+                    minimum: 10,
+                    maximum: 5000,
+                },
+            },
+            required: ["action"],
+        },
+    },
+];
+// Weather simulation
+async function getWeather(location, units) {
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    // Generate deterministic but varied weather based on location
+    const hash = location.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
+    const conditions = ["sunny", "cloudy", "rainy", "partly cloudy", "clear"];
+    const condition = conditions[hash % conditions.length];
+    // Temperature based on condition and some randomness
+    let baseTemp = 20; // celsius
+    if (condition === "sunny")
+        baseTemp = 25;
+    if (condition === "rainy")
+        baseTemp = 15;
+    if (condition === "clear")
+        baseTemp = 22;
+    const tempC = baseTemp + (hash % 10) - 5;
+    const tempF = Math.round((tempC * 9) / 5 + 32);
+    return {
+        location,
+        temperature: units === "fahrenheit" ? tempF : tempC,
+        temperatureUnit: units,
+        conditions: condition,
+        humidity: 40 + (hash % 50),
+        windSpeed: 5 + (hash % 20),
+        windUnit: "km/h",
+        forecast: [
+            { day: "Today", high: tempC + 2, low: tempC - 3, condition },
+            { day: "Tomorrow", high: tempC + 1, low: tempC - 4, condition: conditions[(hash + 1) % conditions.length] },
+            { day: "Day after", high: tempC + 3, low: tempC - 2, condition: conditions[(hash + 2) % conditions.length] },
+        ],
+    };
+}
+// Calculator implementation
+function calculate(operation, a, b) {
+    let result;
+    let expression;
+    switch (operation) {
+        case "add":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for addition");
+            result = a + b;
+            expression = `${a} + ${b}`;
+            break;
+        case "subtract":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for subtraction");
+            result = a - b;
+            expression = `${a} - ${b}`;
+            break;
+        case "multiply":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for multiplication");
+            result = a * b;
+            expression = `${a} * ${b}`;
+            break;
+        case "divide":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for division");
+            if (b === 0)
+                throw new Error("Cannot divide by zero");
+            result = a / b;
+            expression = `${a} / ${b}`;
+            break;
+        case "power":
+            if (b === undefined)
+                throw new Error("Second operand (b) required for power operation");
+            result = Math.pow(a, b);
+            expression = `${a} ^ ${b}`;
+            break;
+        case "sqrt":
+            if (a < 0)
+                throw new Error("Cannot calculate square root of negative number");
+            result = Math.sqrt(a);
+            expression = `sqrt(${a})`;
+            break;
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+    return {
+        operation,
+        expression,
+        operands: { a, b },
+        result,
+        resultType: Number.isInteger(result) ? "integer" : "float",
+    };
+}
+// Database operations
+function databaseQuery(action, id, query, limit) {
+    switch (action) {
+        case "get": {
+            if (!id) {
+                throw new Error("ID required for get action");
+            }
+            const record = simulatedDatabase.get(id);
+            if (!record) {
+                throw new Error(`Record with ID '${id}' not found`);
+            }
+            return {
+                action,
+                record,
+                found: true,
+            };
+        }
+        case "list": {
+            const records = Array.from(simulatedDatabase.values()).slice(0, limit ?? 10);
+            return {
+                action,
+                records,
+                count: records.length,
+                total: simulatedDatabase.size,
+            };
+        }
+        case "search": {
+            if (!query) {
+                throw new Error("Query required for search action");
+            }
+            const queryLower = query.toLowerCase();
+            const records = Array.from(simulatedDatabase.values())
+                .filter((r) => r.name.toLowerCase().includes(queryLower))
+                .slice(0, limit ?? 10);
+            return {
+                action,
+                query,
+                records,
+                count: records.length,
+                total: simulatedDatabase.size,
+            };
+        }
+        default:
+            throw new Error(`Unknown action: ${action}`);
+    }
+}
+// Create MCP server
+const server = new Server({
+    name: "lafs-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: TOOLS,
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const budget = typeof args?._budget === "number" ? args._budget : undefined;
+    try {
+        let result;
+        switch (name) {
+            case "weather": {
+                const location = String(args?.location ?? "");
+                const units = String(args?.units ?? "celsius");
+                if (!location) {
+                    throw new Error("Location is required");
+                }
+                result = await getWeather(location, units);
+                break;
+            }
+            case "calculator": {
+                const operation = String(args?.operation ?? "");
+                const a = Number(args?.a);
+                const b = args?.b !== undefined ? Number(args?.b) : undefined;
+                if (!operation || Number.isNaN(a)) {
+                    throw new Error("Operation and operand 'a' are required");
+                }
+                result = calculate(operation, a, b);
+                break;
+            }
+            case "database_query": {
+                const action = String(args?.action ?? "");
+                const id = args?.id !== undefined ? String(args?.id) : undefined;
+                const query = args?.query !== undefined ? String(args?.query) : undefined;
+                const limit = args?.limit !== undefined ? Number(args?.limit) : undefined;
+                if (!action) {
+                    throw new Error("Action is required");
+                }
+                result = databaseQuery(action, id, query, limit);
+                break;
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        // Create MCP result
+        const mcpResult = {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: false,
+        };
+        // Wrap in LAFS envelope
+        const envelope = wrapMCPResult(mcpResult, `tools/${name}`, budget);
+        // Return the LAFS envelope as text content
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(envelope),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        // Create error MCP result
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const mcpResult = {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessage,
+                },
+            ],
+            isError: true,
+        };
+        // Wrap in LAFS error envelope
+        const envelope = wrapMCPResult(mcpResult, `tools/${name}`, budget);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(envelope),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    console.error("LAFS-MCP Server starting...");
+    console.error("Available tools: weather, calculator, database_query");
+    console.error("All responses are wrapped in LAFS-compliant envelopes");
+    await server.connect(transport);
+    console.error("LAFS-MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/src/a2a/bridge.d.ts

@@ -0,0 +1,129 @@
+/**
+ * LAFS A2A Bridge
+ *
+ * Integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * LAFS provides envelope wrapping and token budget support.
+ */
+import { A2AClient } from '@a2a-js/sdk/client';
+import { Artifact, Part, SendMessageResponse, JSONRPCErrorResponse } from '@a2a-js/sdk';
+export interface LafsA2AConfig {
+    defaultBudget?: {
+        maxTokens?: number;
+        maxItems?: number;
+    };
+    envelopeResponses?: boolean;
+}
+export interface LafsEnvelope {
+    $schema: string;
+    _meta: {
+        specVersion: string;
+        operation: string;
+        requestId: string;
+        mvi: string;
+        _tokenEstimate?: {
+            estimated: number;
+            budget?: number;
+        };
+    };
+    success: boolean;
+    result: unknown;
+    error: null | {
+        code: string;
+        message: string;
+        category: string;
+        retryable: boolean;
+    };
+}
+/**
+ * Wrap A2A client with LAFS envelope support
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@lafs/envelope/a2a';
+ *
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://localhost:4000');
+ *
+ * const client = withLafsEnvelope(a2aClient, {
+ *   envelopeResponses: true,
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * const result = await client.sendMessage({
+ *   message: { role: 'user', parts: [{ text: 'Hello' }] }
+ * });
+ *
+ * // Access LAFS envelope
+ * const envelope = result.getLafsEnvelope();
+ * console.log(envelope._meta._tokenEstimate);
+ * ```
+ */
+export declare function withLafsEnvelope(client: A2AClient, config?: LafsA2AConfig): LafsA2AClient;
+export declare class LafsA2AClient {
+    private client;
+    private config;
+    constructor(client: A2AClient, config: LafsA2AConfig);
+    sendMessage(params: {
+        message: {
+            role: 'user' | 'agent';
+            parts: Part[];
+        };
+        budget?: {
+            maxTokens?: number;
+            maxItems?: number;
+        };
+    }): Promise<LafsA2AResult>;
+    private generateId;
+}
+export declare class LafsA2AResult {
+    private result;
+    private budget;
+    constructor(result: SendMessageResponse, budget: {
+        maxTokens?: number;
+        maxItems?: number;
+    });
+    /**
+     * Get the underlying A2A result
+     */
+    getA2AResult(): SendMessageResponse;
+    /**
+     * Check if result is an error
+     */
+    isError(): boolean;
+    /**
+     * Get error details if result is an error
+     */
+    getError(): JSONRPCErrorResponse | null;
+    /**
+     * Extract LAFS envelope from A2A artifact
+     */
+    getLafsEnvelope(): LafsEnvelope | null;
+    /**
+     * Check if result contains LAFS envelope
+     */
+    hasLafsEnvelope(): boolean;
+    /**
+     * Get token estimate from envelope
+     */
+    getTokenEstimate(): {
+        estimated: number;
+        budget?: number;
+    } | null;
+    private isLafsEnvelope;
+}
+/**
+ * Create a LAFS artifact for A2A
+ *
+ * @example
+ * ```typescript
+ * const artifact = createLafsArtifact({
+ *   success: true,
+ *   result: { data: '...' },
+ *   meta: { operation: 'analysis.run' }
+ * });
+ *
+ * task.artifacts.push(artifact);
+ * ```
+ */
+export declare function createLafsArtifact(envelope: LafsEnvelope): Artifact;

package/dist/src/a2a/bridge.js

@@ -0,0 +1,173 @@
+/**
+ * LAFS A2A Bridge
+ *
+ * Integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * LAFS provides envelope wrapping and token budget support.
+ */
+/**
+ * Wrap A2A client with LAFS envelope support
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@lafs/envelope/a2a';
+ *
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://localhost:4000');
+ *
+ * const client = withLafsEnvelope(a2aClient, {
+ *   envelopeResponses: true,
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * const result = await client.sendMessage({
+ *   message: { role: 'user', parts: [{ text: 'Hello' }] }
+ * });
+ *
+ * // Access LAFS envelope
+ * const envelope = result.getLafsEnvelope();
+ * console.log(envelope._meta._tokenEstimate);
+ * ```
+ */
+export function withLafsEnvelope(client, config = {}) {
+    return new LafsA2AClient(client, config);
+}
+export class LafsA2AClient {
+    client;
+    config;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    async sendMessage(params) {
+        // Merge budget with defaults
+        const budget = {
+            ...this.config.defaultBudget,
+            ...params.budget
+        };
+        // Send via official A2A SDK
+        const result = await this.client.sendMessage({
+            message: {
+                kind: 'message',
+                messageId: this.generateId(),
+                role: params.message.role,
+                parts: params.message.parts
+            }
+        });
+        // Wrap result with LAFS envelope support
+        return new LafsA2AResult(result, budget);
+    }
+    generateId() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+}
+export class LafsA2AResult {
+    result;
+    budget;
+    constructor(result, budget) {
+        this.result = result;
+        this.budget = budget;
+    }
+    /**
+     * Get the underlying A2A result
+     */
+    getA2AResult() {
+        return this.result;
+    }
+    /**
+     * Check if result is an error
+     */
+    isError() {
+        return 'error' in this.result;
+    }
+    /**
+     * Get error details if result is an error
+     */
+    getError() {
+        if (this.isError()) {
+            return this.result;
+        }
+        return null;
+    }
+    /**
+     * Extract LAFS envelope from A2A artifact
+     */
+    getLafsEnvelope() {
+        if (this.isError()) {
+            return null;
+        }
+        const successResult = this.result;
+        // Check if result is a Task
+        if (successResult.result?.kind !== 'task') {
+            return null;
+        }
+        const task = successResult.result;
+        if (!task.artifacts || task.artifacts.length === 0) {
+            return null;
+        }
+        // Find LAFS envelope in artifacts
+        for (const artifact of task.artifacts) {
+            for (const part of artifact.parts) {
+                if (part.kind === 'data' && this.isLafsEnvelope(part.data)) {
+                    return part.data;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if result contains LAFS envelope
+     */
+    hasLafsEnvelope() {
+        return this.getLafsEnvelope() !== null;
+    }
+    /**
+     * Get token estimate from envelope
+     */
+    getTokenEstimate() {
+        const envelope = this.getLafsEnvelope();
+        return envelope?._meta?._tokenEstimate ?? null;
+    }
+    isLafsEnvelope(data) {
+        return (typeof data === 'object' &&
+            data !== null &&
+            '$schema' in data &&
+            '_meta' in data &&
+            'success' in data);
+    }
+}
+/**
+ * Create a LAFS artifact for A2A
+ *
+ * @example
+ * ```typescript
+ * const artifact = createLafsArtifact({
+ *   success: true,
+ *   result: { data: '...' },
+ *   meta: { operation: 'analysis.run' }
+ * });
+ *
+ * task.artifacts.push(artifact);
+ * ```
+ */
+export function createLafsArtifact(envelope) {
+    return {
+        artifactId: generateId(),
+        name: 'lafs_response',
+        parts: [{
+                kind: 'data',
+                data: envelope
+            }]
+    };
+}
+function generateId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}

package/dist/src/a2a/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LAFS Agent-to-Agent (A2A) Integration
+ *
+ * This module provides integration between LAFS and the official
+ * @a2a-js/sdk for Agent-to-Agent communication.
+ *
+ * @example
+ * ```typescript
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ * import { withLafsEnvelope } from '@cleocode/lafs-protocol/a2a';
+ *
+ * // Create official A2A client
+ * const factory = new ClientFactory();
+ * const a2aClient = await factory.createFromUrl('http://agent.example.com');
+ *
+ * // Wrap with LAFS support
+ * const client = withLafsEnvelope(a2aClient, {
+ *   defaultBudget: { maxTokens: 4000 }
+ * });
+ *
+ * // Send message
+ * const result = await client.sendMessage({
+ *   message: {
+ *     role: 'user',
+ *     parts: [{ text: 'Analyze data' }]
+ *   }
+ * });
+ *
+ * // Extract LAFS envelope from response
+ * const envelope = result.getLafsEnvelope();
+ * if (envelope) {
+ *   console.log(envelope._meta._tokenEstimate);
+ * }
+ * ```
+ */
+export { withLafsEnvelope, LafsA2AClient, LafsA2AResult, createLafsArtifact, type LafsA2AConfig, type LafsEnvelope } from './bridge.js';