@cleocode/lafs 2026.4.0 → 2026.4.3

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

@@ -6,98 +6,213 @@
  */
 import type { LAFSError } from '../../types.js';
 import type { A2AErrorType } from './jsonrpc.js';
-/** HTTP+JSON endpoint definitions for each A2A operation */
+/**
+ * HTTP+JSON endpoint definitions for each A2A operation.
+ *
+ * @remarks
+ * Each entry specifies the HTTP method and path template per A2A spec Section 11.3.
+ * Path parameters are prefixed with `:` (e.g. `:id`).
+ */
 export declare const HTTP_ENDPOINTS: {
+    /** Send a single message to an agent */
     readonly SendMessage: {
         readonly method: "POST";
         readonly path: "/message:send";
     };
+    /** Send a streaming message to an agent */
     readonly SendStreamingMessage: {
         readonly method: "POST";
         readonly path: "/message:stream";
     };
+    /** Retrieve a task by identifier */
     readonly GetTask: {
         readonly method: "GET";
         readonly path: "/tasks/:id";
     };
+    /** List tasks matching query criteria */
     readonly ListTasks: {
         readonly method: "GET";
         readonly path: "/tasks";
     };
+    /** Cancel a running task */
     readonly CancelTask: {
         readonly method: "POST";
         readonly path: "/tasks/:id:cancel";
     };
+    /** Subscribe to task events via SSE */
     readonly SubscribeToTask: {
         readonly method: "GET";
         readonly path: "/tasks/:id:subscribe";
     };
+    /** Set push notification configuration for a task */
     readonly SetTaskPushNotificationConfig: {
         readonly method: "POST";
         readonly path: "/tasks/:id/pushNotificationConfig";
     };
+    /** Get push notification configuration for a task */
     readonly GetTaskPushNotificationConfig: {
         readonly method: "GET";
         readonly path: "/tasks/:id/pushNotificationConfig";
     };
+    /** List push notification configurations for a task */
     readonly ListTaskPushNotificationConfig: {
         readonly method: "GET";
         readonly path: "/tasks/:id/pushNotificationConfig:list";
     };
+    /** Delete push notification configuration for a task */
     readonly DeleteTaskPushNotificationConfig: {
         readonly method: "DELETE";
         readonly path: "/tasks/:id/pushNotificationConfig/:configId";
     };
+    /** Retrieve the authenticated extended agent card */
     readonly GetExtendedAgentCard: {
         readonly method: "GET";
         readonly path: "/agent/authenticatedExtendedCard";
     };
 };
+/** Union of all HTTP endpoint descriptor objects from {@link HTTP_ENDPOINTS} */
 export type HttpEndpoint = (typeof HTTP_ENDPOINTS)[keyof typeof HTTP_ENDPOINTS];
-/** Maps A2A error types to HTTP status codes */
+/**
+ * Maps A2A error types to HTTP status codes.
+ *
+ * @remarks
+ * Used by the HTTP binding to determine the appropriate response status
+ * code for each A2A error type per spec Section 5.4.
+ */
 export declare const A2A_HTTP_STATUS_CODES: Record<A2AErrorType, number>;
-/** RFC 9457 Problem Details type URIs for A2A errors */
+/**
+ * RFC 9457 Problem Details type URIs for A2A errors.
+ *
+ * @remarks
+ * Each URI uniquely identifies an A2A error type and is used as the
+ * `type` field in RFC 9457 Problem Details responses.
+ */
 export declare const A2A_ERROR_TYPE_URIS: Record<A2AErrorType, string>;
-/** RFC 9457 Problem Details object */
+/**
+ * RFC 9457 Problem Details object.
+ *
+ * @remarks
+ * Represents a machine-readable error response per RFC 9457. The index
+ * signature allows arbitrary extension members alongside the required fields.
+ */
 export interface ProblemDetails {
+    /** URI reference identifying the problem type */
     type: string;
+    /** Short human-readable summary of the problem */
     title: string;
+    /** HTTP status code for this occurrence */
     status: number;
+    /** Human-readable explanation specific to this occurrence */
     detail: string;
+    /** Extension members (arbitrary key-value pairs) */
     [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
+ *
+ * @remarks
+ * Resolves the `type` URI, `title`, and `status` automatically from
+ * the A2A error type. The title is derived by converting the PascalCase
+ * error type name to title case.
+ *
+ * @param errorType - The A2A error type name (e.g. `"TaskNotFound"`)
+ * @param detail - Human-readable explanation specific to this occurrence
+ * @param extensions - Optional additional members to include in the response
+ * @returns A fully formed {@link ProblemDetails} object
+ *
+ * @example
+ * ```ts
+ * const problem = createProblemDetails('TaskNotFound', 'No task with id xyz');
+ * // { type: 'https://a2a-protocol.org/errors/task-not-found', title: 'Task Not Found', status: 404, detail: '...' }
+ * ```
  */
 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
+ * @remarks
+ * Extends the base Problem Details with LAFS agent-actionable fields such as
+ * `retryable`, `agentAction`, `retryAfterMs`, `escalationRequired`,
+ * `suggestedAction`, and `docUrl` extracted from the provided LAFSError.
+ *
+ * @param errorType - The A2A error type name (e.g. `"InvalidAgentResponse"`)
  * @param lafsError - The LAFS error object to extract extension fields from
- * @param requestId - Optional request identifier for the `instance` field
+ * @param requestId - Optional request identifier used as the `instance` field
+ * @returns A {@link ProblemDetails} object with LAFS extension fields
+ *
+ * @example
+ * ```ts
+ * const problem = createLafsProblemDetails('InvalidAgentResponse', {
+ *   code: 'E_AGENT_RESPONSE',
+ *   message: 'Upstream agent returned invalid JSON',
+ *   retryable: true,
+ *   retryAfterMs: 5000,
+ * }, 'req-123');
+ * ```
  */
 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)
+ *
+ * @remarks
+ * Replaces `:param` placeholders in the endpoint path template with
+ * URI-encoded values from the `params` object.
+ *
+ * @param endpoint - HTTP endpoint definition from {@link HTTP_ENDPOINTS}
+ * @param params - Path parameter values keyed by name (without leading colon)
+ * @returns The resolved URL path string with parameters substituted
+ *
+ * @example
+ * ```ts
+ * const url = buildUrl(HTTP_ENDPOINTS.GetTask, { id: 'task-42' });
+ * // '/tasks/task-42'
+ * ```
  */
 export declare function buildUrl(endpoint: HttpEndpoint, params?: Record<string, string>): string;
-/** Parsed query parameters for ListTasks (spec Section 11.5) */
+/**
+ * Parsed query parameters for the ListTasks endpoint.
+ *
+ * @remarks
+ * Represents the camelCase query parameters defined in A2A spec Section 11.5.
+ * All fields are optional for flexible filtering.
+ */
 export interface ListTasksQueryParams {
+    /**
+     * Filter tasks by context identifier.
+     * @defaultValue undefined
+     */
     contextId?: string;
+    /**
+     * Filter tasks by state (e.g. `"submitted"`, `"working"`).
+     * @defaultValue undefined
+     */
     state?: string;
+    /**
+     * Maximum number of tasks to return.
+     * @defaultValue undefined
+     */
     limit?: number;
+    /**
+     * Pagination token from a previous response.
+     * @defaultValue undefined
+     */
     pageToken?: string;
 }
 /**
  * Parse camelCase query parameters for the ListTasks endpoint.
- * Handles type coercion for numeric fields.
+ *
+ * @remarks
+ * Handles type coercion for numeric fields (e.g. `limit` is parsed from
+ * string to integer). Undefined values are preserved as-is.
+ *
+ * @param query - Raw query parameter map from the HTTP request
+ * @returns A typed {@link ListTasksQueryParams} object with coerced values
+ *
+ * @example
+ * ```ts
+ * const params = parseListTasksQuery({ contextId: 'ctx-1', limit: '10' });
+ * // { contextId: 'ctx-1', limit: 10 }
+ * ```
  */
 export declare function parseListTasksQuery(query: Record<string, string | undefined>): ListTasksQueryParams;
 //# sourceMappingURL=http.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../../src/a2a/bindings/http.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD,4DAA4D;AAC5D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAejB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAMhF,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAUrD,CAAC;AAMX,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAWnD,CAAC;AAMX,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,cAAc,CAWhB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,SAAS,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAehB;AAMD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQxF;AAMD,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACxC,oBAAoB,CAOtB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../../src/a2a/bindings/http.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMjD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;IACzB,wCAAwC;;;;;IAExC,2CAA2C;;;;;IAE3C,oCAAoC;;;;;IAEpC,yCAAyC;;;;;IAEzC,4BAA4B;;;;;IAE5B,uCAAuC;;;;;IAEvC,qDAAqD;;;;;IAErD,qDAAqD;;;;;IAErD,uDAAuD;;;;;IAEvD,wDAAwD;;;;;IAKxD,qDAAqD;;;;;CAE7C,CAAC;AAEX,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAMhF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAUrD,CAAC;AAMX;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAWnD,CAAC;AAMX;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,cAAc,CAWhB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,SAAS,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAehB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQxF;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACxC,oBAAoB,CAOtB"}

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

@@ -7,27 +7,50 @@
 // ============================================================================
 // Endpoint Constants (spec Section 11.3)
 // ============================================================================
-/** HTTP+JSON endpoint definitions for each A2A operation */
+/**
+ * HTTP+JSON endpoint definitions for each A2A operation.
+ *
+ * @remarks
+ * Each entry specifies the HTTP method and path template per A2A spec Section 11.3.
+ * Path parameters are prefixed with `:` (e.g. `:id`).
+ */
 export const HTTP_ENDPOINTS = {
+    /** Send a single message to an agent */
     SendMessage: { method: 'POST', path: '/message:send' },
+    /** Send a streaming message to an agent */
     SendStreamingMessage: { method: 'POST', path: '/message:stream' },
+    /** Retrieve a task by identifier */
     GetTask: { method: 'GET', path: '/tasks/:id' },
+    /** List tasks matching query criteria */
     ListTasks: { method: 'GET', path: '/tasks' },
+    /** Cancel a running task */
     CancelTask: { method: 'POST', path: '/tasks/:id:cancel' },
+    /** Subscribe to task events via SSE */
     SubscribeToTask: { method: 'GET', path: '/tasks/:id:subscribe' },
+    /** Set push notification configuration for a task */
     SetTaskPushNotificationConfig: { method: 'POST', path: '/tasks/:id/pushNotificationConfig' },
+    /** Get push notification configuration for a task */
     GetTaskPushNotificationConfig: { method: 'GET', path: '/tasks/:id/pushNotificationConfig' },
+    /** List push notification configurations for a task */
     ListTaskPushNotificationConfig: { method: 'GET', path: '/tasks/:id/pushNotificationConfig:list' },
+    /** Delete push notification configuration for a task */
     DeleteTaskPushNotificationConfig: {
         method: 'DELETE',
         path: '/tasks/:id/pushNotificationConfig/:configId',
     },
+    /** Retrieve the authenticated extended agent card */
     GetExtendedAgentCard: { method: 'GET', path: '/agent/authenticatedExtendedCard' },
 };
 // ============================================================================
 // HTTP Status Codes (spec Section 5.4)
 // ============================================================================
-/** Maps A2A error types to HTTP status codes */
+/**
+ * Maps A2A error types to HTTP status codes.
+ *
+ * @remarks
+ * Used by the HTTP binding to determine the appropriate response status
+ * code for each A2A error type per spec Section 5.4.
+ */
 export const A2A_HTTP_STATUS_CODES = {
     TaskNotFound: 404,
     TaskNotCancelable: 409,
@@ -42,7 +65,13 @@ export const A2A_HTTP_STATUS_CODES = {
 // ============================================================================
 // Error Type URIs (spec Section 5.4)
 // ============================================================================
-/** RFC 9457 Problem Details type URIs for A2A errors */
+/**
+ * RFC 9457 Problem Details type URIs for A2A errors.
+ *
+ * @remarks
+ * Each URI uniquely identifies an A2A error type and is used as the
+ * `type` field in RFC 9457 Problem Details responses.
+ */
 export const A2A_ERROR_TYPE_URIS = {
     TaskNotFound: 'https://a2a-protocol.org/errors/task-not-found',
     TaskNotCancelable: 'https://a2a-protocol.org/errors/task-not-cancelable',
@@ -56,9 +85,22 @@ export const A2A_ERROR_TYPE_URIS = {
 };
 /**
  * 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
+ *
+ * @remarks
+ * Resolves the `type` URI, `title`, and `status` automatically from
+ * the A2A error type. The title is derived by converting the PascalCase
+ * error type name to title case.
+ *
+ * @param errorType - The A2A error type name (e.g. `"TaskNotFound"`)
+ * @param detail - Human-readable explanation specific to this occurrence
+ * @param extensions - Optional additional members to include in the response
+ * @returns A fully formed {@link ProblemDetails} object
+ *
+ * @example
+ * ```ts
+ * const problem = createProblemDetails('TaskNotFound', 'No task with id xyz');
+ * // { type: 'https://a2a-protocol.org/errors/task-not-found', title: 'Task Not Found', status: 404, detail: '...' }
+ * ```
  */
 export function createProblemDetails(errorType, detail, extensions) {
     // Convert PascalCase to Title Case: "TaskNotFound" -> "Task Not Found"
@@ -73,11 +115,26 @@ export function createProblemDetails(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
+ * @remarks
+ * Extends the base Problem Details with LAFS agent-actionable fields such as
+ * `retryable`, `agentAction`, `retryAfterMs`, `escalationRequired`,
+ * `suggestedAction`, and `docUrl` extracted from the provided LAFSError.
+ *
+ * @param errorType - The A2A error type name (e.g. `"InvalidAgentResponse"`)
  * @param lafsError - The LAFS error object to extract extension fields from
- * @param requestId - Optional request identifier for the `instance` field
+ * @param requestId - Optional request identifier used as the `instance` field
+ * @returns A {@link ProblemDetails} object with LAFS extension fields
+ *
+ * @example
+ * ```ts
+ * const problem = createLafsProblemDetails('InvalidAgentResponse', {
+ *   code: 'E_AGENT_RESPONSE',
+ *   message: 'Upstream agent returned invalid JSON',
+ *   retryable: true,
+ *   retryAfterMs: 5000,
+ * }, 'req-123');
+ * ```
  */
 export function createLafsProblemDetails(errorType, lafsError, requestId) {
     const base = createProblemDetails(errorType, lafsError.message);
@@ -99,8 +156,20 @@ export function createLafsProblemDetails(errorType, lafsError, requestId) {
 // ============================================================================
 /**
  * Build a URL by substituting path parameters.
- * @param endpoint - HTTP endpoint definition (from HTTP_ENDPOINTS)
- * @param params - Path parameter values (keys without leading colon)
+ *
+ * @remarks
+ * Replaces `:param` placeholders in the endpoint path template with
+ * URI-encoded values from the `params` object.
+ *
+ * @param endpoint - HTTP endpoint definition from {@link HTTP_ENDPOINTS}
+ * @param params - Path parameter values keyed by name (without leading colon)
+ * @returns The resolved URL path string with parameters substituted
+ *
+ * @example
+ * ```ts
+ * const url = buildUrl(HTTP_ENDPOINTS.GetTask, { id: 'task-42' });
+ * // '/tasks/task-42'
+ * ```
  */
 export function buildUrl(endpoint, params) {
     let path = endpoint.path;
@@ -113,7 +182,19 @@ export function buildUrl(endpoint, params) {
 }
 /**
  * Parse camelCase query parameters for the ListTasks endpoint.
- * Handles type coercion for numeric fields.
+ *
+ * @remarks
+ * Handles type coercion for numeric fields (e.g. `limit` is parsed from
+ * string to integer). Undefined values are preserved as-is.
+ *
+ * @param query - Raw query parameter map from the HTTP request
+ * @returns A typed {@link ListTasksQueryParams} object with coerced values
+ *
+ * @example
+ * ```ts
+ * const params = parseListTasksQuery({ contextId: 'ctx-1', limit: '10' });
+ * // { contextId: 'ctx-1', limit: 10 }
+ * ```
  */
 export function parseListTasksQuery(query) {
     return {

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

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../../src/a2a/bindings/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../../src/a2a/bindings/http.ts"],"names":[],"mappings":"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"}

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

@@ -3,34 +3,107 @@
  *
  * Re-exports all binding modules and provides cross-binding
  * error code mapping for consistent error handling across transports.
+ *
+ * @packageDocumentation
  */
 export * from './grpc.js';
 export * from './http.js';
 export * from './jsonrpc.js';
 import { type A2AErrorType } from './jsonrpc.js';
-/** Complete error code mapping across all three transports */
+/**
+ * Complete error code mapping across all three transports.
+ *
+ * @remarks
+ * Provides a unified view of how a single A2A error type maps to
+ * JSON-RPC, HTTP, and gRPC error representations.
+ */
 export interface ErrorCodeMapping {
-    /** JSON-RPC numeric error code */
+    /** JSON-RPC numeric error code (e.g. `-32001`) */
     jsonRpcCode: number;
-    /** HTTP response status code */
+    /** HTTP response status code (e.g. `404`) */
     httpStatus: number;
     /** RFC 9457 Problem Details type URI */
     httpTypeUri: string;
-    /** gRPC status name (e.g. NOT_FOUND) */
+    /** gRPC status name (e.g. `"NOT_FOUND"`) */
     grpcStatus: string;
-    /** gRPC numeric status code */
+    /** gRPC numeric status code (e.g. `5`) */
     grpcCode: number;
 }
-/** Precomputed cross-binding error mapping for all 9 A2A error types */
+/**
+ * Precomputed cross-binding error mapping for all 9 A2A error types.
+ *
+ * @remarks
+ * Built once at module load and immutable thereafter. Each entry maps an
+ * A2A error type to its JSON-RPC, HTTP, and gRPC representations.
+ */
 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.
+ *
+ * @remarks
+ * Looks up the precomputed mapping from {@link A2A_ERROR_MAPPINGS}. Throws
+ * if the error type is not one of the 9 known A2A error types.
+ *
+ * @param errorType - The A2A error type name (e.g. `"TaskNotFound"`)
+ * @returns The {@link ErrorCodeMapping} with JSON-RPC, HTTP, and gRPC codes
+ * @throws Error if the error type is not a known A2A error type
+ *
+ * @example
+ * ```ts
+ * const mapping = getErrorCodeMapping('TaskNotFound');
+ * // { jsonRpcCode: -32001, httpStatus: 404, httpTypeUri: '...', grpcStatus: 'NOT_FOUND', grpcCode: 5 }
+ * ```
  */
 export declare function getErrorCodeMapping(errorType: A2AErrorType): ErrorCodeMapping;
 export { A2A_GRPC_ERROR_REASONS } from './grpc.js';
+/**
+ * Supported A2A protocol versions.
+ *
+ * @remarks
+ * Tuple of version strings that this implementation can handle.
+ */
 export declare const SUPPORTED_A2A_VERSIONS: readonly ["1.0"];
+/**
+ * Default A2A protocol version used when none is requested.
+ *
+ * @remarks
+ * Applied when the client does not provide an `a2a-version` header.
+ */
 export declare const DEFAULT_A2A_VERSION: "1.0";
+/**
+ * Parse the `a2a-version` header into an array of version strings.
+ *
+ * @remarks
+ * Splits the comma-separated header value, trims whitespace, and filters
+ * empty segments. Returns an empty array when the header is absent.
+ *
+ * @param headerValue - The raw `a2a-version` header value, or `undefined` if absent
+ * @returns An array of version strings extracted from the header
+ *
+ * @example
+ * ```ts
+ * parseA2AVersionHeader('1.0, 2.0'); // ['1.0', '2.0']
+ * parseA2AVersionHeader(undefined);   // []
+ * ```
+ */
 export declare function parseA2AVersionHeader(headerValue: string | undefined): string[];
+/**
+ * Negotiate an A2A protocol version from the client's requested versions.
+ *
+ * @remarks
+ * Returns the first requested version that is also in {@link SUPPORTED_A2A_VERSIONS}.
+ * Falls back to {@link DEFAULT_A2A_VERSION} when the request list is empty.
+ * Returns `null` if no requested version is supported.
+ *
+ * @param requestedVersions - Array of version strings requested by the client
+ * @returns The negotiated version string, or `null` if no common version exists
+ *
+ * @example
+ * ```ts
+ * negotiateA2AVersion(['1.0', '2.0']); // '1.0'
+ * negotiateA2AVersion([]);              // '1.0' (default)
+ * negotiateA2AVersion(['3.0']);          // null
+ * ```
+ */
 export declare function negotiateA2AVersion(requestedVersions: string[]): string | null;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/a2a/bindings/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAI7B,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,cAAc,CAAC;AAM1E,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAgCD,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,YAAY,EAAE,gBAAgB,CAAmB,CAAC;AAE/F;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,YAAY,GAAG,gBAAgB,CAM7E;AAID,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAMnD,eAAO,MAAM,sBAAsB,kBAAmB,CAAC;AACvD,eAAO,MAAM,mBAAmB,EAAG,KAAc,CAAC;AAElD,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAM/E;AAED,wBAAgB,mBAAmB,CAAC,iBAAiB,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAY9E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/a2a/bindings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAI7B,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,cAAc,CAAC;AAM1E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAgCD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,YAAY,EAAE,gBAAgB,CAAmB,CAAC;AAE/F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,YAAY,GAAG,gBAAgB,CAM7E;AAID,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAMnD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,kBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAG,KAAc,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAM/E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,iBAAiB,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAY9E"}

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

@@ -3,6 +3,8 @@
  *
  * Re-exports all binding modules and provides cross-binding
  * error code mapping for consistent error handling across transports.
+ *
+ * @packageDocumentation
  */
 export * from './grpc.js';
 export * from './http.js';
@@ -36,11 +38,30 @@ function buildMappings() {
     }
     return map;
 }
-/** Precomputed cross-binding error mapping for all 9 A2A error types */
+/**
+ * Precomputed cross-binding error mapping for all 9 A2A error types.
+ *
+ * @remarks
+ * Built once at module load and immutable thereafter. Each entry maps an
+ * A2A error type to its JSON-RPC, HTTP, and gRPC representations.
+ */
 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.
+ *
+ * @remarks
+ * Looks up the precomputed mapping from {@link A2A_ERROR_MAPPINGS}. Throws
+ * if the error type is not one of the 9 known A2A error types.
+ *
+ * @param errorType - The A2A error type name (e.g. `"TaskNotFound"`)
+ * @returns The {@link ErrorCodeMapping} with JSON-RPC, HTTP, and gRPC codes
+ * @throws Error if the error type is not a known A2A error type
+ *
+ * @example
+ * ```ts
+ * const mapping = getErrorCodeMapping('TaskNotFound');
+ * // { jsonRpcCode: -32001, httpStatus: 404, httpTypeUri: '...', grpcStatus: 'NOT_FOUND', grpcCode: 5 }
+ * ```
  */
 export function getErrorCodeMapping(errorType) {
     const mapping = A2A_ERROR_MAPPINGS.get(errorType);
@@ -55,8 +76,36 @@ export { A2A_GRPC_ERROR_REASONS } from './grpc.js';
 // ============================================================================
 // Version Negotiation
 // ============================================================================
+/**
+ * Supported A2A protocol versions.
+ *
+ * @remarks
+ * Tuple of version strings that this implementation can handle.
+ */
 export const SUPPORTED_A2A_VERSIONS = ['1.0'];
+/**
+ * Default A2A protocol version used when none is requested.
+ *
+ * @remarks
+ * Applied when the client does not provide an `a2a-version` header.
+ */
 export const DEFAULT_A2A_VERSION = '1.0';
+/**
+ * Parse the `a2a-version` header into an array of version strings.
+ *
+ * @remarks
+ * Splits the comma-separated header value, trims whitespace, and filters
+ * empty segments. Returns an empty array when the header is absent.
+ *
+ * @param headerValue - The raw `a2a-version` header value, or `undefined` if absent
+ * @returns An array of version strings extracted from the header
+ *
+ * @example
+ * ```ts
+ * parseA2AVersionHeader('1.0, 2.0'); // ['1.0', '2.0']
+ * parseA2AVersionHeader(undefined);   // []
+ * ```
+ */
 export function parseA2AVersionHeader(headerValue) {
     if (!headerValue)
         return [];
@@ -65,6 +114,24 @@ export function parseA2AVersionHeader(headerValue) {
         .map((v) => v.trim())
         .filter(Boolean);
 }
+/**
+ * Negotiate an A2A protocol version from the client's requested versions.
+ *
+ * @remarks
+ * Returns the first requested version that is also in {@link SUPPORTED_A2A_VERSIONS}.
+ * Falls back to {@link DEFAULT_A2A_VERSION} when the request list is empty.
+ * Returns `null` if no requested version is supported.
+ *
+ * @param requestedVersions - Array of version strings requested by the client
+ * @returns The negotiated version string, or `null` if no common version exists
+ *
+ * @example
+ * ```ts
+ * negotiateA2AVersion(['1.0', '2.0']); // '1.0'
+ * negotiateA2AVersion([]);              // '1.0' (default)
+ * negotiateA2AVersion(['3.0']);          // null
+ * ```
+ */
 export function negotiateA2AVersion(requestedVersions) {
     if (requestedVersions.length === 0) {
         return DEFAULT_A2A_VERSION;

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/a2a/bindings/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAqB,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAoB1E,4BAA4B;AAC5B,MAAM,WAAW,GAAmB;IAClC,cAAc;IACd,mBAAmB;IACnB,8BAA8B;IAC9B,sBAAsB;IACtB,yBAAyB;IACzB,sBAAsB;IACtB,wCAAwC;IACxC,0BAA0B;IAC1B,qBAAqB;CACtB,CAAC;AAEF,SAAS,aAAa;IACpB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkC,CAAC;IAEtD,KAAK,MAAM,SAAS,IAAI,WAAW,EAAE,CAAC;QACpC,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACxD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE;YACjB,WAAW,EAAE,uBAAuB,CAAC,SAAS,CAAC;YAC/C,UAAU,EAAE,qBAAqB,CAAC,SAAS,CAAC;YAC5C,WAAW,EAAE,mBAAmB,CAAC,SAAS,CAAC;YAC3C,UAAU,EAAE,cAAc;YAC1B,QAAQ,EAAE,gBAAgB,CAAC,cAAc,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,kBAAkB,GAAgD,aAAa,EAAE,CAAC;AAE/F;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAuB;IACzD,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,SAAS,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,sFAAsF;AACtF,mFAAmF;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAK,CAAU,CAAC;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAc,CAAC;AAElD,MAAM,UAAU,qBAAqB,CAAC,WAA+B;IACnE,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,CAAC;IAC5B,OAAO,WAAW;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,iBAA2B;IAC7D,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAClD,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;QACxC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAkD,CAAC,EAAE,CAAC;YACtE,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/a2a/bindings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAqB,uBAAuB,EAAE,MAAM,cAAc,CAAC;AA0B1E,4BAA4B;AAC5B,MAAM,WAAW,GAAmB;IAClC,cAAc;IACd,mBAAmB;IACnB,8BAA8B;IAC9B,sBAAsB;IACtB,yBAAyB;IACzB,sBAAsB;IACtB,wCAAwC;IACxC,0BAA0B;IAC1B,qBAAqB;CACtB,CAAC;AAEF,SAAS,aAAa;IACpB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkC,CAAC;IAEtD,KAAK,MAAM,SAAS,IAAI,WAAW,EAAE,CAAC;QACpC,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACxD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE;YACjB,WAAW,EAAE,uBAAuB,CAAC,SAAS,CAAC;YAC/C,UAAU,EAAE,qBAAqB,CAAC,SAAS,CAAC;YAC5C,WAAW,EAAE,mBAAmB,CAAC,SAAS,CAAC;YAC3C,UAAU,EAAE,cAAc;YAC1B,QAAQ,EAAE,gBAAgB,CAAC,cAAc,CAAC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgD,aAAa,EAAE,CAAC;AAE/F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAuB;IACzD,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,SAAS,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,sFAAsF;AACtF,mFAAmF;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAK,CAAU,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAc,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAA+B;IACnE,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,CAAC;IAC5B,OAAO,WAAW;SACf,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,iBAA2B;IAC7D,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAClD,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;QACxC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAkD,CAAC,EAAE,CAAC;YACtE,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}