@cleocode/lafs 1.8.0

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

@@ -0,0 +1,162 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "version": "1.0.0",
+    "codes": [
+        {
+            "code": "E_FORMAT_CONFLICT",
+            "category": "CONTRACT",
+            "description": "Mutually exclusive format flags requested",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2,
+            "agentAction": "stop",
+            "typeUri": "https://lafs.dev/errors/v1/format-conflict",
+            "docUrl": "https://lafs.dev/docs/errors/format-conflict"
+        },
+        {
+            "code": "E_VALIDATION_SCHEMA",
+            "category": "VALIDATION",
+            "description": "Input failed schema validation",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2,
+            "agentAction": "retry_modified",
+            "typeUri": "https://lafs.dev/errors/v1/validation-schema",
+            "docUrl": "https://lafs.dev/docs/errors/validation-schema"
+        },
+        {
+            "code": "E_NOT_FOUND_RESOURCE",
+            "category": "NOT_FOUND",
+            "description": "Referenced resource was not found",
+            "retryable": false,
+            "httpStatus": 404,
+            "grpcStatus": "NOT_FOUND",
+            "cliExit": 4,
+            "agentAction": "stop",
+            "typeUri": "https://lafs.dev/errors/v1/not-found-resource",
+            "docUrl": "https://lafs.dev/docs/errors/not-found-resource"
+        },
+        {
+            "code": "E_CONFLICT_VERSION",
+            "category": "CONFLICT",
+            "description": "Version or concurrency conflict",
+            "retryable": true,
+            "httpStatus": 409,
+            "grpcStatus": "ABORTED",
+            "cliExit": 7,
+            "agentAction": "refresh_context",
+            "typeUri": "https://lafs.dev/errors/v1/conflict-version",
+            "docUrl": "https://lafs.dev/docs/errors/conflict-version"
+        },
+        {
+            "code": "E_RATE_LIMITED",
+            "category": "RATE_LIMIT",
+            "description": "Rate limit exceeded",
+            "retryable": true,
+            "httpStatus": 429,
+            "grpcStatus": "RESOURCE_EXHAUSTED",
+            "cliExit": 8,
+            "agentAction": "wait",
+            "typeUri": "https://lafs.dev/errors/v1/rate-limited",
+            "docUrl": "https://lafs.dev/docs/errors/rate-limited"
+        },
+        {
+            "code": "E_TRANSIENT_UPSTREAM",
+            "category": "TRANSIENT",
+            "description": "Upstream dependency temporary failure",
+            "retryable": true,
+            "httpStatus": 503,
+            "grpcStatus": "UNAVAILABLE",
+            "cliExit": 9,
+            "agentAction": "retry",
+            "typeUri": "https://lafs.dev/errors/v1/transient-upstream",
+            "docUrl": "https://lafs.dev/docs/errors/transient-upstream"
+        },
+        {
+            "code": "E_INTERNAL_UNEXPECTED",
+            "category": "INTERNAL",
+            "description": "Unexpected internal failure",
+            "retryable": false,
+            "httpStatus": 500,
+            "grpcStatus": "INTERNAL",
+            "cliExit": 1,
+            "agentAction": "escalate",
+            "typeUri": "https://lafs.dev/errors/v1/internal-unexpected",
+            "docUrl": "https://lafs.dev/docs/errors/internal-unexpected"
+        },
+        {
+            "code": "E_CONTEXT_MISSING",
+            "category": "CONTRACT",
+            "description": "Required context ledger fields are missing",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "FAILED_PRECONDITION",
+            "cliExit": 6,
+            "agentAction": "retry_modified",
+            "typeUri": "https://lafs.dev/errors/v1/context-missing",
+            "docUrl": "https://lafs.dev/docs/errors/context-missing"
+        },
+        {
+            "code": "E_CONTEXT_STALE",
+            "category": "CONFLICT",
+            "description": "Context ledger or references are stale",
+            "retryable": true,
+            "httpStatus": 409,
+            "grpcStatus": "ABORTED",
+            "cliExit": 7,
+            "agentAction": "refresh_context",
+            "typeUri": "https://lafs.dev/errors/v1/context-stale",
+            "docUrl": "https://lafs.dev/docs/errors/context-stale"
+        },
+        {
+            "code": "E_MIGRATION_UNSUPPORTED_VERSION",
+            "category": "MIGRATION",
+            "description": "Requested protocol/schema version unsupported",
+            "retryable": false,
+            "httpStatus": 426,
+            "grpcStatus": "FAILED_PRECONDITION",
+            "cliExit": 10,
+            "agentAction": "stop",
+            "typeUri": "https://lafs.dev/errors/v1/migration-unsupported-version",
+            "docUrl": "https://lafs.dev/docs/errors/migration-unsupported-version"
+        },
+        {
+            "code": "E_DISCLOSURE_UNKNOWN_FIELD",
+            "category": "VALIDATION",
+            "description": "Unrecognized expansion field in _expand parameter",
+            "retryable": false,
+            "httpStatus": 400,
+            "grpcStatus": "INVALID_ARGUMENT",
+            "cliExit": 2,
+            "agentAction": "retry_modified",
+            "typeUri": "https://lafs.dev/errors/v1/disclosure-unknown-field",
+            "docUrl": "https://lafs.dev/docs/errors/disclosure-unknown-field"
+        },
+        {
+            "code": "E_MVI_BUDGET_EXCEEDED",
+            "category": "VALIDATION",
+            "description": "Response exceeds declared MVI budget (token, byte, or item limit)",
+            "retryable": false,
+            "httpStatus": 413,
+            "grpcStatus": "RESOURCE_EXHAUSTED",
+            "cliExit": 2,
+            "agentAction": "retry_modified",
+            "typeUri": "https://lafs.dev/errors/v1/mvi-budget-exceeded",
+            "docUrl": "https://lafs.dev/docs/errors/mvi-budget-exceeded"
+        },
+        {
+            "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,
+            "agentAction": "stop",
+            "typeUri": "https://lafs.dev/errors/v1/field-conflict",
+            "docUrl": "https://lafs.dev/docs/errors/field-conflict"
+        }
+    ]
+}

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

@@ -0,0 +1,67 @@
+/**
+ * A2A gRPC Protocol Binding
+ *
+ * Status codes, error reasons, service method definitions, and metadata
+ * constants for gRPC transport. Types and helpers only — no @grpc/grpc-js
+ * runtime dependency.
+ *
+ * Reference: A2A spec Section 10.3-10.6
+ */
+import type { A2AErrorType } from './jsonrpc.js';
+/** Standard gRPC status codes (numeric values 0-16) */
+export declare const GRPC_STATUS_CODE: {
+    readonly OK: 0;
+    readonly CANCELLED: 1;
+    readonly UNKNOWN: 2;
+    readonly INVALID_ARGUMENT: 3;
+    readonly DEADLINE_EXCEEDED: 4;
+    readonly NOT_FOUND: 5;
+    readonly ALREADY_EXISTS: 6;
+    readonly PERMISSION_DENIED: 7;
+    readonly RESOURCE_EXHAUSTED: 8;
+    readonly FAILED_PRECONDITION: 9;
+    readonly ABORTED: 10;
+    readonly OUT_OF_RANGE: 11;
+    readonly UNIMPLEMENTED: 12;
+    readonly INTERNAL: 13;
+    readonly UNAVAILABLE: 14;
+    readonly DATA_LOSS: 15;
+    readonly UNAUTHENTICATED: 16;
+};
+export type GrpcStatusCode = (typeof GRPC_STATUS_CODE)[keyof typeof GRPC_STATUS_CODE];
+export type GrpcStatusName = keyof typeof GRPC_STATUS_CODE;
+/** Maps A2A error types to gRPC status names */
+export declare const A2A_GRPC_STATUS_CODES: Record<A2AErrorType, GrpcStatusName>;
+/** UPPER_SNAKE_CASE error reasons without "Error" suffix */
+export declare const A2A_GRPC_ERROR_REASONS: Record<A2AErrorType, string>;
+/** Error domain for A2A gRPC errors */
+export declare const A2A_GRPC_ERROR_DOMAIN: "a2a-protocol.org";
+/** gRPC service method descriptor */
+export interface GrpcServiceMethod {
+    request: string;
+    response: string;
+    streaming: boolean;
+}
+/** gRPC service method definitions for the A2A protocol */
+export declare const GRPC_SERVICE_METHODS: Record<string, GrpcServiceMethod>;
+/** gRPC metadata key for A2A protocol version */
+export declare const GRPC_METADATA_VERSION_KEY: "a2a-version";
+/** gRPC metadata key for activated A2A extensions */
+export declare const GRPC_METADATA_EXTENSIONS_KEY: "a2a-extensions";
+/** gRPC Status object for A2A errors */
+export interface GrpcStatus {
+    code: GrpcStatusCode;
+    message: string;
+    details?: GrpcErrorInfo[];
+}
+/** google.rpc.ErrorInfo equivalent */
+export interface GrpcErrorInfo {
+    reason: string;
+    domain: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Create a gRPC Status object for an A2A error type.
+ * Includes ErrorInfo details with reason and domain.
+ */
+export declare function createGrpcStatus(errorType: A2AErrorType, message: string, metadata?: Record<string, string>): GrpcStatus;

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

@@ -0,0 +1,148 @@
+/**
+ * A2A gRPC Protocol Binding
+ *
+ * Status codes, error reasons, service method definitions, and metadata
+ * constants for gRPC transport. Types and helpers only — no @grpc/grpc-js
+ * runtime dependency.
+ *
+ * Reference: A2A spec Section 10.3-10.6
+ */
+// ============================================================================
+// gRPC Status Codes (standard)
+// ============================================================================
+/** Standard gRPC status codes (numeric values 0-16) */
+export const GRPC_STATUS_CODE = {
+    OK: 0,
+    CANCELLED: 1,
+    UNKNOWN: 2,
+    INVALID_ARGUMENT: 3,
+    DEADLINE_EXCEEDED: 4,
+    NOT_FOUND: 5,
+    ALREADY_EXISTS: 6,
+    PERMISSION_DENIED: 7,
+    RESOURCE_EXHAUSTED: 8,
+    FAILED_PRECONDITION: 9,
+    ABORTED: 10,
+    OUT_OF_RANGE: 11,
+    UNIMPLEMENTED: 12,
+    INTERNAL: 13,
+    UNAVAILABLE: 14,
+    DATA_LOSS: 15,
+    UNAUTHENTICATED: 16,
+};
+// ============================================================================
+// A2A gRPC Status Mapping (spec Section 5.4)
+// ============================================================================
+/** Maps A2A error types to gRPC status names */
+export const A2A_GRPC_STATUS_CODES = {
+    TaskNotFound: 'NOT_FOUND',
+    TaskNotCancelable: 'FAILED_PRECONDITION',
+    PushNotificationNotSupported: 'UNIMPLEMENTED',
+    UnsupportedOperation: 'UNIMPLEMENTED',
+    ContentTypeNotSupported: 'INVALID_ARGUMENT',
+    InvalidAgentResponse: 'INTERNAL',
+    AuthenticatedExtendedCardNotConfigured: 'NOT_FOUND',
+    ExtensionSupportRequired: 'FAILED_PRECONDITION',
+    VersionNotSupported: 'FAILED_PRECONDITION',
+};
+// ============================================================================
+// Error Reasons (spec Section 10.6)
+// ============================================================================
+/** UPPER_SNAKE_CASE error reasons without "Error" suffix */
+export const A2A_GRPC_ERROR_REASONS = {
+    TaskNotFound: 'TASK_NOT_FOUND',
+    TaskNotCancelable: 'TASK_NOT_CANCELABLE',
+    PushNotificationNotSupported: 'PUSH_NOTIFICATION_NOT_SUPPORTED',
+    UnsupportedOperation: 'UNSUPPORTED_OPERATION',
+    ContentTypeNotSupported: 'CONTENT_TYPE_NOT_SUPPORTED',
+    InvalidAgentResponse: 'INVALID_AGENT_RESPONSE',
+    AuthenticatedExtendedCardNotConfigured: 'AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED',
+    ExtensionSupportRequired: 'EXTENSION_SUPPORT_REQUIRED',
+    VersionNotSupported: 'VERSION_NOT_SUPPORTED',
+};
+/** Error domain for A2A gRPC errors */
+export const A2A_GRPC_ERROR_DOMAIN = 'a2a-protocol.org';
+/** gRPC service method definitions for the A2A protocol */
+export const GRPC_SERVICE_METHODS = {
+    SendMessage: {
+        request: 'MessageSendParams',
+        response: 'SendMessageResponse',
+        streaming: false,
+    },
+    SendStreamingMessage: {
+        request: 'MessageSendParams',
+        response: 'SendStreamingMessageResponse',
+        streaming: true,
+    },
+    GetTask: {
+        request: 'TaskQueryParams',
+        response: 'GetTaskResponse',
+        streaming: false,
+    },
+    ListTasks: {
+        request: 'TaskQueryParams',
+        response: 'ListTasksResponse',
+        streaming: false,
+    },
+    CancelTask: {
+        request: 'TaskIdParams',
+        response: 'CancelTaskResponse',
+        streaming: false,
+    },
+    SubscribeToTask: {
+        request: 'TaskIdParams',
+        response: 'SubscribeToTaskResponse',
+        streaming: true,
+    },
+    SetTaskPushNotificationConfig: {
+        request: 'TaskPushNotificationConfig',
+        response: 'SetTaskPushNotificationConfigResponse',
+        streaming: false,
+    },
+    GetTaskPushNotificationConfig: {
+        request: 'GetTaskPushNotificationConfigParams',
+        response: 'GetTaskPushNotificationConfigResponse',
+        streaming: false,
+    },
+    ListTaskPushNotificationConfig: {
+        request: 'ListTaskPushNotificationConfigParams',
+        response: 'ListTaskPushNotificationConfigResponse',
+        streaming: false,
+    },
+    DeleteTaskPushNotificationConfig: {
+        request: 'DeleteTaskPushNotificationConfigParams',
+        response: 'DeleteTaskPushNotificationConfigResponse',
+        streaming: false,
+    },
+    GetExtendedAgentCard: {
+        request: 'GetAuthenticatedExtendedCardRequest',
+        response: 'GetAuthenticatedExtendedCardResponse',
+        streaming: false,
+    },
+};
+// ============================================================================
+// gRPC Metadata Constants
+// ============================================================================
+/** gRPC metadata key for A2A protocol version */
+export const GRPC_METADATA_VERSION_KEY = 'a2a-version';
+/** gRPC metadata key for activated A2A extensions */
+export const GRPC_METADATA_EXTENSIONS_KEY = 'a2a-extensions';
+/**
+ * Create a gRPC Status object for an A2A error type.
+ * Includes ErrorInfo details with reason and domain.
+ */
+export function createGrpcStatus(errorType, message, metadata) {
+    const statusName = A2A_GRPC_STATUS_CODES[errorType];
+    const code = GRPC_STATUS_CODE[statusName];
+    return {
+        code,
+        message,
+        details: [
+            {
+                reason: A2A_GRPC_ERROR_REASONS[errorType],
+                domain: A2A_GRPC_ERROR_DOMAIN,
+                ...(metadata && { metadata }),
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,102 @@
+/**
+ * A2A HTTP Protocol Binding
+ *
+ * HTTP endpoint definitions, status codes, error type URIs,
+ * and RFC 9457 Problem Details support per A2A spec Section 11.3-11.5.
+ */
+import type { A2AErrorType } from './jsonrpc.js';
+import type { LAFSError } from '../../types.js';
+/** HTTP+JSON endpoint definitions for each A2A operation */
+export declare const HTTP_ENDPOINTS: {
+    readonly SendMessage: {
+        readonly method: "POST";
+        readonly path: "/message:send";
+    };
+    readonly SendStreamingMessage: {
+        readonly method: "POST";
+        readonly path: "/message:stream";
+    };
+    readonly GetTask: {
+        readonly method: "GET";
+        readonly path: "/tasks/:id";
+    };
+    readonly ListTasks: {
+        readonly method: "GET";
+        readonly path: "/tasks";
+    };
+    readonly CancelTask: {
+        readonly method: "POST";
+        readonly path: "/tasks/:id:cancel";
+    };
+    readonly SubscribeToTask: {
+        readonly method: "GET";
+        readonly path: "/tasks/:id:subscribe";
+    };
+    readonly SetTaskPushNotificationConfig: {
+        readonly method: "POST";
+        readonly path: "/tasks/:id/pushNotificationConfig";
+    };
+    readonly GetTaskPushNotificationConfig: {
+        readonly method: "GET";
+        readonly path: "/tasks/:id/pushNotificationConfig";
+    };
+    readonly ListTaskPushNotificationConfig: {
+        readonly method: "GET";
+        readonly path: "/tasks/:id/pushNotificationConfig:list";
+    };
+    readonly DeleteTaskPushNotificationConfig: {
+        readonly method: "DELETE";
+        readonly path: "/tasks/:id/pushNotificationConfig/:configId";
+    };
+    readonly GetExtendedAgentCard: {
+        readonly method: "GET";
+        readonly path: "/agent/authenticatedExtendedCard";
+    };
+};
+export type HttpEndpoint = (typeof HTTP_ENDPOINTS)[keyof typeof HTTP_ENDPOINTS];
+/** Maps A2A error types to HTTP status codes */
+export declare const A2A_HTTP_STATUS_CODES: Record<A2AErrorType, number>;
+/** RFC 9457 Problem Details type URIs for A2A errors */
+export declare const A2A_ERROR_TYPE_URIS: Record<A2AErrorType, string>;
+/** RFC 9457 Problem Details object */
+export interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    [key: string]: unknown;
+}
+/**
+ * Create an RFC 9457 Problem Details object for an A2A error.
+ * @param errorType - The A2A error type name
+ * @param detail - Human-readable explanation of the error
+ * @param extensions - Additional members to include in the response
+ */
+export declare function createProblemDetails(errorType: A2AErrorType, detail: string, extensions?: Record<string, unknown>): ProblemDetails;
+/**
+ * Create an RFC 9457 Problem Details object bridging A2A error types with LAFS error data.
+ * Includes LAFS agent-actionable extension fields from the LAFSError.
+ *
+ * @param errorType - The A2A error type name
+ * @param lafsError - The LAFS error object to extract extension fields from
+ * @param requestId - Optional request identifier for the `instance` field
+ */
+export declare function createLafsProblemDetails(errorType: A2AErrorType, lafsError: LAFSError, requestId?: string): ProblemDetails;
+/**
+ * Build a URL by substituting path parameters.
+ * @param endpoint - HTTP endpoint definition (from HTTP_ENDPOINTS)
+ * @param params - Path parameter values (keys without leading colon)
+ */
+export declare function buildUrl(endpoint: HttpEndpoint, params?: Record<string, string>): string;
+/** Parsed query parameters for ListTasks (spec Section 11.5) */
+export interface ListTasksQueryParams {
+    contextId?: string;
+    state?: string;
+    limit?: number;
+    pageToken?: string;
+}
+/**
+ * Parse camelCase query parameters for the ListTasks endpoint.
+ * Handles type coercion for numeric fields.
+ */
+export declare function parseListTasksQuery(query: Record<string, string | undefined>): ListTasksQueryParams;

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

@@ -0,0 +1,120 @@
+/**
+ * A2A HTTP Protocol Binding
+ *
+ * HTTP endpoint definitions, status codes, error type URIs,
+ * and RFC 9457 Problem Details support per A2A spec Section 11.3-11.5.
+ */
+// ============================================================================
+// Endpoint Constants (spec Section 11.3)
+// ============================================================================
+/** HTTP+JSON endpoint definitions for each A2A operation */
+export const HTTP_ENDPOINTS = {
+    SendMessage: { method: 'POST', path: '/message:send' },
+    SendStreamingMessage: { method: 'POST', path: '/message:stream' },
+    GetTask: { method: 'GET', path: '/tasks/:id' },
+    ListTasks: { method: 'GET', path: '/tasks' },
+    CancelTask: { method: 'POST', path: '/tasks/:id:cancel' },
+    SubscribeToTask: { method: 'GET', path: '/tasks/:id:subscribe' },
+    SetTaskPushNotificationConfig: { method: 'POST', path: '/tasks/:id/pushNotificationConfig' },
+    GetTaskPushNotificationConfig: { method: 'GET', path: '/tasks/:id/pushNotificationConfig' },
+    ListTaskPushNotificationConfig: { method: 'GET', path: '/tasks/:id/pushNotificationConfig:list' },
+    DeleteTaskPushNotificationConfig: { method: 'DELETE', path: '/tasks/:id/pushNotificationConfig/:configId' },
+    GetExtendedAgentCard: { method: 'GET', path: '/agent/authenticatedExtendedCard' },
+};
+// ============================================================================
+// HTTP Status Codes (spec Section 5.4)
+// ============================================================================
+/** Maps A2A error types to HTTP status codes */
+export const A2A_HTTP_STATUS_CODES = {
+    TaskNotFound: 404,
+    TaskNotCancelable: 409,
+    PushNotificationNotSupported: 400,
+    UnsupportedOperation: 400,
+    ContentTypeNotSupported: 415,
+    InvalidAgentResponse: 502,
+    AuthenticatedExtendedCardNotConfigured: 404,
+    ExtensionSupportRequired: 400,
+    VersionNotSupported: 400,
+};
+// ============================================================================
+// Error Type URIs (spec Section 5.4)
+// ============================================================================
+/** RFC 9457 Problem Details type URIs for A2A errors */
+export const A2A_ERROR_TYPE_URIS = {
+    TaskNotFound: 'https://a2a-protocol.org/errors/task-not-found',
+    TaskNotCancelable: 'https://a2a-protocol.org/errors/task-not-cancelable',
+    PushNotificationNotSupported: 'https://a2a-protocol.org/errors/push-notification-not-supported',
+    UnsupportedOperation: 'https://a2a-protocol.org/errors/unsupported-operation',
+    ContentTypeNotSupported: 'https://a2a-protocol.org/errors/content-type-not-supported',
+    InvalidAgentResponse: 'https://a2a-protocol.org/errors/invalid-agent-response',
+    AuthenticatedExtendedCardNotConfigured: 'https://a2a-protocol.org/errors/authenticated-extended-card-not-configured',
+    ExtensionSupportRequired: 'https://a2a-protocol.org/errors/extension-support-required',
+    VersionNotSupported: 'https://a2a-protocol.org/errors/version-not-supported',
+};
+/**
+ * Create an RFC 9457 Problem Details object for an A2A error.
+ * @param errorType - The A2A error type name
+ * @param detail - Human-readable explanation of the error
+ * @param extensions - Additional members to include in the response
+ */
+export function createProblemDetails(errorType, detail, extensions) {
+    // Convert PascalCase to Title Case: "TaskNotFound" -> "Task Not Found"
+    const title = errorType.replace(/([A-Z])/g, ' $1').trim();
+    return {
+        type: A2A_ERROR_TYPE_URIS[errorType],
+        title,
+        status: A2A_HTTP_STATUS_CODES[errorType],
+        detail,
+        ...extensions,
+    };
+}
+/**
+ * Create an RFC 9457 Problem Details object bridging A2A error types with LAFS error data.
+ * Includes LAFS agent-actionable extension fields from the LAFSError.
+ *
+ * @param errorType - The A2A error type name
+ * @param lafsError - The LAFS error object to extract extension fields from
+ * @param requestId - Optional request identifier for the `instance` field
+ */
+export function createLafsProblemDetails(errorType, lafsError, requestId) {
+    const base = createProblemDetails(errorType, lafsError.message);
+    return {
+        ...base,
+        ...(requestId != null && { instance: requestId }),
+        retryable: lafsError.retryable,
+        ...(lafsError.agentAction != null && { agentAction: lafsError.agentAction }),
+        ...(lafsError.retryAfterMs != null && { retryAfterMs: lafsError.retryAfterMs }),
+        ...(lafsError.escalationRequired != null && { escalationRequired: lafsError.escalationRequired }),
+        ...(lafsError.suggestedAction != null && { suggestedAction: lafsError.suggestedAction }),
+        ...(lafsError.docUrl != null && { docUrl: lafsError.docUrl }),
+    };
+}
+// ============================================================================
+// URL Building
+// ============================================================================
+/**
+ * Build a URL by substituting path parameters.
+ * @param endpoint - HTTP endpoint definition (from HTTP_ENDPOINTS)
+ * @param params - Path parameter values (keys without leading colon)
+ */
+export function buildUrl(endpoint, params) {
+    let path = endpoint.path;
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            path = path.replace(`:${key}`, encodeURIComponent(value));
+        }
+    }
+    return path;
+}
+/**
+ * Parse camelCase query parameters for the ListTasks endpoint.
+ * Handles type coercion for numeric fields.
+ */
+export function parseListTasksQuery(query) {
+    return {
+        contextId: query['contextId'],
+        state: query['state'],
+        limit: query['limit'] ? parseInt(query['limit'], 10) : undefined,
+        pageToken: query['pageToken'],
+    };
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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 { type A2AErrorType } from './jsonrpc.js';
+/** Complete error code mapping across all three transports */
+export interface ErrorCodeMapping {
+    /** JSON-RPC numeric error code */
+    jsonRpcCode: number;
+    /** HTTP response status code */
+    httpStatus: number;
+    /** RFC 9457 Problem Details type URI */
+    httpTypeUri: string;
+    /** gRPC status name (e.g. NOT_FOUND) */
+    grpcStatus: string;
+    /** gRPC numeric status code */
+    grpcCode: number;
+}
+/** Precomputed cross-binding error mapping for all 9 A2A error types */
+export declare const A2A_ERROR_MAPPINGS: ReadonlyMap<A2AErrorType, ErrorCodeMapping>;
+/**
+ * Get the complete error code mapping for a given A2A error type.
+ * Returns consistent values across JSON-RPC, HTTP, and gRPC.
+ */
+export declare function getErrorCodeMapping(errorType: A2AErrorType): ErrorCodeMapping;
+export { A2A_GRPC_ERROR_REASONS } from './grpc.js';
+export declare const SUPPORTED_A2A_VERSIONS: readonly ["1.0"];
+export declare const DEFAULT_A2A_VERSION: "1.0";
+export declare function parseA2AVersionHeader(headerValue: string | undefined): string[];
+export declare function negotiateA2AVersion(requestedVersions: string[]): string | null;