@cleocode/lafs 1.8.0

package/dist/src/a2a/bindings/index.js

@@ -0,0 +1,79 @@
+/**
+ * A2A Protocol Bindings - Barrel Export
+ *
+ * Re-exports all binding modules and provides cross-binding
+ * error code mapping for consistent error handling across transports.
+ */
+export * from './jsonrpc.js';
+export * from './http.js';
+export * from './grpc.js';
+import { JSONRPC_A2A_ERROR_CODES } from './jsonrpc.js';
+import { A2A_HTTP_STATUS_CODES, A2A_ERROR_TYPE_URIS } from './http.js';
+import { A2A_GRPC_STATUS_CODES, GRPC_STATUS_CODE } from './grpc.js';
+/** All 9 A2A error types */
+const ERROR_TYPES = [
+    'TaskNotFound',
+    'TaskNotCancelable',
+    'PushNotificationNotSupported',
+    'UnsupportedOperation',
+    'ContentTypeNotSupported',
+    'InvalidAgentResponse',
+    'AuthenticatedExtendedCardNotConfigured',
+    'ExtensionSupportRequired',
+    'VersionNotSupported',
+];
+function buildMappings() {
+    const map = new Map();
+    for (const errorType of ERROR_TYPES) {
+        const grpcStatusName = A2A_GRPC_STATUS_CODES[errorType];
+        map.set(errorType, {
+            jsonRpcCode: JSONRPC_A2A_ERROR_CODES[errorType],
+            httpStatus: A2A_HTTP_STATUS_CODES[errorType],
+            httpTypeUri: A2A_ERROR_TYPE_URIS[errorType],
+            grpcStatus: grpcStatusName,
+            grpcCode: GRPC_STATUS_CODE[grpcStatusName],
+        });
+    }
+    return map;
+}
+/** Precomputed cross-binding error mapping for all 9 A2A error types */
+export const A2A_ERROR_MAPPINGS = buildMappings();
+/**
+ * Get the complete error code mapping for a given A2A error type.
+ * Returns consistent values across JSON-RPC, HTTP, and gRPC.
+ */
+export function getErrorCodeMapping(errorType) {
+    const mapping = A2A_ERROR_MAPPINGS.get(errorType);
+    if (!mapping) {
+        throw new Error(`Unknown A2A error type: ${errorType}`);
+    }
+    return mapping;
+}
+// Also export A2A_GRPC_ERROR_REASONS for convenience (re-exported from grpc.ts via *)
+// but explicitly reference it here so the cross-binding module is self-documenting
+export { A2A_GRPC_ERROR_REASONS } from './grpc.js';
+// ============================================================================
+// Version Negotiation
+// ============================================================================
+export const SUPPORTED_A2A_VERSIONS = ['1.0'];
+export const DEFAULT_A2A_VERSION = '1.0';
+export function parseA2AVersionHeader(headerValue) {
+    if (!headerValue)
+        return [];
+    return headerValue
+        .split(',')
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+export function negotiateA2AVersion(requestedVersions) {
+    if (requestedVersions.length === 0) {
+        return DEFAULT_A2A_VERSION;
+    }
+    const supported = new Set(SUPPORTED_A2A_VERSIONS);
+    for (const version of requestedVersions) {
+        if (supported.has(version)) {
+            return version;
+        }
+    }
+    return null;
+}

package/dist/src/a2a/bindings/jsonrpc.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A2A JSON-RPC Protocol Binding
+ *
+ * Method constants, error codes, and request/response builders
+ * for JSON-RPC 2.0 transport per A2A spec Section 5.3-5.4.
+ */
+/** All JSON-RPC method names defined by the A2A protocol */
+export declare const JSONRPC_METHODS: {
+    readonly SendMessage: "message/send";
+    readonly SendStreamingMessage: "message/stream";
+    readonly GetTask: "tasks/get";
+    readonly ListTasks: "tasks/list";
+    readonly CancelTask: "tasks/cancel";
+    readonly SubscribeToTask: "tasks/resubscribe";
+    readonly SetTaskPushNotificationConfig: "tasks/pushNotificationConfig/set";
+    readonly GetTaskPushNotificationConfig: "tasks/pushNotificationConfig/get";
+    readonly ListTaskPushNotificationConfig: "tasks/pushNotificationConfig/list";
+    readonly DeleteTaskPushNotificationConfig: "tasks/pushNotificationConfig/delete";
+    readonly GetExtendedAgentCard: "agent/getAuthenticatedExtendedCard";
+};
+export type JsonRpcMethod = (typeof JSONRPC_METHODS)[keyof typeof JSONRPC_METHODS];
+/** Standard JSON-RPC 2.0 error codes */
+export declare const JSONRPC_STANDARD_ERROR_CODES: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+};
+/** A2A-specific error codes (-32001 through -32009) */
+export declare const JSONRPC_A2A_ERROR_CODES: {
+    readonly TaskNotFound: -32001;
+    readonly TaskNotCancelable: -32002;
+    readonly PushNotificationNotSupported: -32003;
+    readonly UnsupportedOperation: -32004;
+    readonly ContentTypeNotSupported: -32005;
+    readonly InvalidAgentResponse: -32006;
+    readonly AuthenticatedExtendedCardNotConfigured: -32007;
+    readonly ExtensionSupportRequired: -32008;
+    readonly VersionNotSupported: -32009;
+};
+export type A2AErrorType = keyof typeof JSONRPC_A2A_ERROR_CODES;
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: Record<string, unknown>;
+    };
+}
+/** Create a JSON-RPC 2.0 request object */
+export declare function createJsonRpcRequest(id: string | number, method: string, params?: Record<string, unknown>): JsonRpcRequest;
+/** Create a JSON-RPC 2.0 success response */
+export declare function createJsonRpcResponse(id: string | number | null, result: unknown): JsonRpcResponse;
+/** Create a JSON-RPC 2.0 error response */
+export declare function createJsonRpcErrorResponse(id: string | number | null, code: number, message: string, data?: Record<string, unknown>): JsonRpcErrorResponse;
+/** Create an A2A-specific JSON-RPC error response by error type name */
+export declare function createA2AErrorResponse(id: string | number | null, errorType: A2AErrorType, message: string, data?: Record<string, unknown>): JsonRpcErrorResponse;
+/** Validate the structure of a JSON-RPC request */
+export declare function validateJsonRpcRequest(input: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/** Check if a numeric error code is an A2A-specific error */
+export declare function isA2AError(code: number): boolean;

package/dist/src/a2a/bindings/jsonrpc.js

@@ -0,0 +1,114 @@
+/**
+ * A2A JSON-RPC Protocol Binding
+ *
+ * Method constants, error codes, and request/response builders
+ * for JSON-RPC 2.0 transport per A2A spec Section 5.3-5.4.
+ */
+// ============================================================================
+// Method Constants (spec Section 5.3)
+// ============================================================================
+/** All JSON-RPC method names defined by the A2A protocol */
+export const JSONRPC_METHODS = {
+    SendMessage: 'message/send',
+    SendStreamingMessage: 'message/stream',
+    GetTask: 'tasks/get',
+    ListTasks: 'tasks/list',
+    CancelTask: 'tasks/cancel',
+    SubscribeToTask: 'tasks/resubscribe',
+    SetTaskPushNotificationConfig: 'tasks/pushNotificationConfig/set',
+    GetTaskPushNotificationConfig: 'tasks/pushNotificationConfig/get',
+    ListTaskPushNotificationConfig: 'tasks/pushNotificationConfig/list',
+    DeleteTaskPushNotificationConfig: 'tasks/pushNotificationConfig/delete',
+    GetExtendedAgentCard: 'agent/getAuthenticatedExtendedCard',
+};
+// ============================================================================
+// Error Code Constants (spec Section 5.4)
+// ============================================================================
+/** Standard JSON-RPC 2.0 error codes */
+export const JSONRPC_STANDARD_ERROR_CODES = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+};
+/** A2A-specific error codes (-32001 through -32009) */
+export const JSONRPC_A2A_ERROR_CODES = {
+    TaskNotFound: -32001,
+    TaskNotCancelable: -32002,
+    PushNotificationNotSupported: -32003,
+    UnsupportedOperation: -32004,
+    ContentTypeNotSupported: -32005,
+    InvalidAgentResponse: -32006,
+    AuthenticatedExtendedCardNotConfigured: -32007,
+    ExtensionSupportRequired: -32008,
+    VersionNotSupported: -32009,
+};
+// ============================================================================
+// Builders
+// ============================================================================
+/** Create a JSON-RPC 2.0 request object */
+export function createJsonRpcRequest(id, method, params) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        method,
+        ...(params !== undefined && { params }),
+    };
+}
+/** Create a JSON-RPC 2.0 success response */
+export function createJsonRpcResponse(id, result) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result,
+    };
+}
+/** Create a JSON-RPC 2.0 error response */
+export function createJsonRpcErrorResponse(id, code, message, data) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code,
+            message,
+            ...(data !== undefined && { data }),
+        },
+    };
+}
+/** Create an A2A-specific JSON-RPC error response by error type name */
+export function createA2AErrorResponse(id, errorType, message, data) {
+    return createJsonRpcErrorResponse(id, JSONRPC_A2A_ERROR_CODES[errorType], message, data);
+}
+// ============================================================================
+// Validation
+// ============================================================================
+const knownMethods = new Set(Object.values(JSONRPC_METHODS));
+/** Validate the structure of a JSON-RPC request */
+export function validateJsonRpcRequest(input) {
+    const errors = [];
+    if (typeof input !== 'object' || input === null) {
+        return { valid: false, errors: ['Input must be an object'] };
+    }
+    const obj = input;
+    if (obj['jsonrpc'] !== '2.0') {
+        errors.push('jsonrpc must be "2.0"');
+    }
+    if (obj['id'] === undefined || (typeof obj['id'] !== 'string' && typeof obj['id'] !== 'number')) {
+        errors.push('id must be a string or number');
+    }
+    if (typeof obj['method'] !== 'string') {
+        errors.push('method must be a string');
+    }
+    else if (!knownMethods.has(obj['method'])) {
+        errors.push(`Unknown method: ${obj['method']}`);
+    }
+    if (obj['params'] !== undefined && (typeof obj['params'] !== 'object' || obj['params'] === null)) {
+        errors.push('params must be an object when provided');
+    }
+    return { valid: errors.length === 0, errors };
+}
+/** Check if a numeric error code is an A2A-specific error */
+export function isA2AError(code) {
+    return code >= -32009 && code <= -32001;
+}

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

@@ -0,0 +1,175 @@
+/**
+ * LAFS A2A Bridge v2.0
+ *
+ * Full integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * Implements A2A Protocol v1.0+ specification.
+ *
+ * Reference: specs/external/specification.md
+ */
+import { AGENT_CARD_PATH, HTTP_EXTENSION_HEADER } from '@a2a-js/sdk';
+import type { Task, TaskState, TaskStatus, Artifact, Part, Message, AgentCard, MessageSendConfiguration, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse } from '@a2a-js/sdk';
+import type { LAFSEnvelope } from '../types.js';
+/**
+ * Configuration for LAFS A2A integration
+ */
+export interface LafsA2AConfig {
+    /** Default token budget for all operations */
+    defaultBudget?: {
+        maxTokens?: number;
+        maxItems?: number;
+        maxBytes?: number;
+    };
+    /** Whether to automatically wrap responses in LAFS envelopes */
+    envelopeResponses?: boolean;
+    /** A2A protocol version to use (default: "1.0") */
+    protocolVersion?: string;
+    /** Extension URIs to activate for all requests */
+    defaultExtensions?: string[];
+}
+/**
+ * Request parameters for sending messages
+ */
+export interface LafsSendMessageParams {
+    /** Message content */
+    message: {
+        role: 'user' | 'agent';
+        parts: Part[];
+        /** Optional message metadata */
+        metadata?: Record<string, unknown>;
+    };
+    /** A2A configuration for this request */
+    configuration?: MessageSendConfiguration;
+    /** Token budget override */
+    budget?: {
+        maxTokens?: number;
+        maxItems?: number;
+        maxBytes?: number;
+    };
+    /** Extensions to activate for this request */
+    extensions?: string[];
+    /** Context ID for multi-turn conversations */
+    contextId?: string;
+    /** Task ID for continuing existing task */
+    taskId?: string;
+}
+/**
+ * Wrapper for A2A responses with LAFS envelope support
+ */
+export declare class LafsA2AResult {
+    private result;
+    private config;
+    private requestId;
+    constructor(result: SendMessageResponse, config: LafsA2AConfig, requestId: string);
+    /**
+     * Get the raw A2A response
+     */
+    getA2AResult(): SendMessageResponse;
+    /**
+     * Check if result is an error
+     */
+    isError(): boolean;
+    /**
+     * Get error details if result is an error
+     */
+    getError(): JSONRPCErrorResponse | null;
+    /**
+     * Get success result
+     */
+    getSuccess(): SendMessageSuccessResponse | null;
+    /**
+     * Extract Task from response (if present)
+     */
+    getTask(): Task | null;
+    /**
+     * Extract Message from response (if present)
+     */
+    getMessage(): Message | null;
+    /**
+     * Check if response contains a LAFS envelope
+     */
+    hasLafsEnvelope(): boolean;
+    /**
+     * Extract LAFS envelope from A2A artifact
+     *
+     * A2A agents can return LAFS envelopes in artifacts for structured data.
+     * This method extracts the envelope from the first artifact containing one.
+     */
+    getLafsEnvelope(): LAFSEnvelope | null;
+    /**
+     * Get token estimate from LAFS envelope
+     */
+    getTokenEstimate(): {
+        estimated: number;
+        budget?: number;
+        truncated?: boolean;
+    } | null;
+    /**
+     * Get task status
+     */
+    getTaskStatus(): TaskStatus | null;
+    /**
+     * Get task state
+     */
+    getTaskState(): TaskState | null;
+    /**
+     * Check if task is in a terminal state
+     */
+    isTerminal(): boolean;
+    /**
+     * Check if task requires input
+     */
+    isInputRequired(): boolean;
+    /**
+     * Check if task requires authentication
+     */
+    isAuthRequired(): boolean;
+    /**
+     * Get all artifacts from task
+     */
+    getArtifacts(): Artifact[];
+    private isDataPart;
+    private isLafsEnvelope;
+}
+/**
+ * Create a LAFS envelope artifact for A2A
+ *
+ * @example
+ * ```typescript
+ * const envelope = createEnvelope({
+ *   success: true,
+ *   result: { data: '...' },
+ *   meta: { operation: 'analysis.run' }
+ * });
+ *
+ * const artifact = createLafsArtifact(envelope);
+ * task.artifacts.push(artifact);
+ * ```
+ */
+export declare function createLafsArtifact(envelope: LAFSEnvelope): Artifact;
+/**
+ * Create a text artifact
+ */
+export declare function createTextArtifact(text: string, name?: string): Artifact;
+/**
+ * Create a file artifact
+ */
+export declare function createFileArtifact(fileUrl: string, mediaType: string, filename?: string): Artifact;
+/**
+ * Check if an extension is required
+ */
+export declare function isExtensionRequired(agentCard: AgentCard, extensionUri: string): boolean;
+/**
+ * Get extension parameters
+ */
+export declare function getExtensionParams(agentCard: AgentCard, extensionUri: string): Record<string, unknown> | undefined;
+/**
+ * A2A Agent Card well-known path
+ * Reference: specs/external/agent-discovery.md
+ */
+export { AGENT_CARD_PATH };
+/**
+ * HTTP header for A2A Extensions
+ * Reference: specs/external/extensions.md
+ */
+export { HTTP_EXTENSION_HEADER };
+export type { Task, TaskState, TaskStatus, Artifact, Part, Message, AgentCard, AgentSkill, AgentCapabilities, AgentExtension, PushNotificationConfig, MessageSendConfiguration, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse, TextPart, DataPart, FilePart, } from '@a2a-js/sdk';