@cleocode/lafs-protocol 1.2.3 → 1.3.1

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

@@ -1,90 +1,66 @@
 /**
- * LAFS A2A Bridge
+ * LAFS A2A Bridge v2.0
  *
- * Integration with official @a2a-js/sdk for Agent-to-Agent communication.
- * LAFS provides envelope wrapping and token budget support.
+ * Full integration with official @a2a-js/sdk for Agent-to-Agent communication.
+ * Implements A2A Protocol v1.0+ specification.
+ *
+ * Reference: specs/external/specification.md
+ */
+import type { Task, TaskState, TaskStatus, Artifact, Part, Message, AgentCard, MessageSendConfiguration, SendMessageResponse, SendMessageSuccessResponse, JSONRPCErrorResponse, AGENT_CARD_PATH, HTTP_EXTENSION_HEADER } from '@a2a-js/sdk';
+import type { LAFSEnvelope } from '../types.js';
+/**
+ * Configuration for LAFS A2A integration
  */
-import { A2AClient } from '@a2a-js/sdk/client';
-import { Artifact, Part, SendMessageResponse, JSONRPCErrorResponse } from '@a2a-js/sdk';
 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[];
 }
-export interface LafsEnvelope {
-    $schema: string;
-    _meta: {
-        specVersion: string;
-        operation: string;
-        requestId: string;
-        mvi: string;
-        _tokenEstimate?: {
-            estimated: number;
-            budget?: number;
-        };
+/**
+ * Request parameters for sending messages
+ */
+export interface LafsSendMessageParams {
+    /** Message content */
+    message: {
+        role: 'user' | 'agent';
+        parts: Part[];
+        /** Optional message metadata */
+        metadata?: Record<string, unknown>;
     };
-    success: boolean;
-    result: unknown;
-    error: null | {
-        code: string;
-        message: string;
-        category: string;
-        retryable: boolean;
+    /** 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;
 }
 /**
- * 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);
- * ```
+ * Wrapper for A2A responses with LAFS envelope support
  */
-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;
-    });
+    private config;
+    private requestId;
+    constructor(result: SendMessageResponse, config: LafsA2AConfig, requestId: string);
     /**
-     * Get the underlying A2A result
+     * Get the raw A2A response
      */
     getA2AResult(): SendMessageResponse;
     /**
@@ -96,34 +72,103 @@ export declare class LafsA2AResult {
      */
     getError(): JSONRPCErrorResponse | null;
     /**
-     * Extract LAFS envelope from A2A artifact
+     * Get success result
+     */
+    getSuccess(): SendMessageSuccessResponse | null;
+    /**
+     * Extract Task from response (if present)
+     */
+    getTask(): Task | null;
+    /**
+     * Extract Message from response (if present)
      */
-    getLafsEnvelope(): LafsEnvelope | null;
+    getMessage(): Message | null;
     /**
-     * Check if result contains LAFS envelope
+     * Check if response contains a LAFS envelope
      */
     hasLafsEnvelope(): boolean;
     /**
-     * Get token estimate from envelope
+     * 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 artifact for A2A
+ * Create a LAFS envelope artifact for A2A
  *
  * @example
  * ```typescript
- * const artifact = createLafsArtifact({
+ * 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;
+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';