@cleocode/lafs 2026.4.0 → 2026.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +97 -68
  2. package/dist/src/a2a/bindings/grpc.d.ts +117 -11
  3. package/dist/src/a2a/bindings/grpc.d.ts.map +1 -1
  4. package/dist/src/a2a/bindings/grpc.js +79 -8
  5. package/dist/src/a2a/bindings/grpc.js.map +1 -1
  6. package/dist/src/a2a/bindings/http.d.ts +129 -14
  7. package/dist/src/a2a/bindings/http.d.ts.map +1 -1
  8. package/dist/src/a2a/bindings/http.js +93 -12
  9. package/dist/src/a2a/bindings/http.js.map +1 -1
  10. package/dist/src/a2a/bindings/index.d.ts +80 -7
  11. package/dist/src/a2a/bindings/index.d.ts.map +1 -1
  12. package/dist/src/a2a/bindings/index.js +69 -2
  13. package/dist/src/a2a/bindings/index.js.map +1 -1
  14. package/dist/src/a2a/bindings/jsonrpc.d.ts +193 -9
  15. package/dist/src/a2a/bindings/jsonrpc.d.ts.map +1 -1
  16. package/dist/src/a2a/bindings/jsonrpc.js +152 -9
  17. package/dist/src/a2a/bindings/jsonrpc.js.map +1 -1
  18. package/dist/src/a2a/bridge.d.ts +232 -37
  19. package/dist/src/a2a/bridge.d.ts.map +1 -1
  20. package/dist/src/a2a/bridge.js +172 -24
  21. package/dist/src/a2a/bridge.js.map +1 -1
  22. package/dist/src/a2a/extensions.d.ts +221 -12
  23. package/dist/src/a2a/extensions.d.ts.map +1 -1
  24. package/dist/src/a2a/extensions.js +175 -11
  25. package/dist/src/a2a/extensions.js.map +1 -1
  26. package/dist/src/a2a/index.d.ts +2 -0
  27. package/dist/src/a2a/index.d.ts.map +1 -1
  28. package/dist/src/a2a/index.js +2 -0
  29. package/dist/src/a2a/index.js.map +1 -1
  30. package/dist/src/a2a/streaming.d.ts +274 -2
  31. package/dist/src/a2a/streaming.d.ts.map +1 -1
  32. package/dist/src/a2a/streaming.js +245 -2
  33. package/dist/src/a2a/streaming.js.map +1 -1
  34. package/dist/src/a2a/task-lifecycle.d.ts +339 -19
  35. package/dist/src/a2a/task-lifecycle.d.ts.map +1 -1
  36. package/dist/src/a2a/task-lifecycle.js +302 -19
  37. package/dist/src/a2a/task-lifecycle.js.map +1 -1
  38. package/dist/src/budgetEnforcement.d.ts +88 -14
  39. package/dist/src/budgetEnforcement.d.ts.map +1 -1
  40. package/dist/src/budgetEnforcement.js +132 -19
  41. package/dist/src/budgetEnforcement.js.map +1 -1
  42. package/dist/src/circuit-breaker/index.d.ts +254 -9
  43. package/dist/src/circuit-breaker/index.d.ts.map +1 -1
  44. package/dist/src/circuit-breaker/index.js +218 -9
  45. package/dist/src/circuit-breaker/index.js.map +1 -1
  46. package/dist/src/compliance.d.ts +176 -0
  47. package/dist/src/compliance.d.ts.map +1 -1
  48. package/dist/src/compliance.js +100 -0
  49. package/dist/src/compliance.js.map +1 -1
  50. package/dist/src/conformance.d.ts +52 -0
  51. package/dist/src/conformance.d.ts.map +1 -1
  52. package/dist/src/conformance.js +41 -0
  53. package/dist/src/conformance.js.map +1 -1
  54. package/dist/src/conformanceProfiles.d.ts +66 -0
  55. package/dist/src/conformanceProfiles.d.ts.map +1 -1
  56. package/dist/src/conformanceProfiles.js +51 -0
  57. package/dist/src/conformanceProfiles.js.map +1 -1
  58. package/dist/src/deprecationRegistry.d.ts +80 -0
  59. package/dist/src/deprecationRegistry.d.ts.map +1 -1
  60. package/dist/src/deprecationRegistry.js +50 -0
  61. package/dist/src/deprecationRegistry.js.map +1 -1
  62. package/dist/src/discovery.d.ts +344 -63
  63. package/dist/src/discovery.d.ts.map +1 -1
  64. package/dist/src/discovery.js +67 -13
  65. package/dist/src/discovery.js.map +1 -1
  66. package/dist/src/envelope.d.ts +252 -0
  67. package/dist/src/envelope.d.ts.map +1 -1
  68. package/dist/src/envelope.js +165 -0
  69. package/dist/src/envelope.js.map +1 -1
  70. package/dist/src/errorRegistry.d.ts +159 -0
  71. package/dist/src/errorRegistry.d.ts.map +1 -1
  72. package/dist/src/errorRegistry.js +115 -0
  73. package/dist/src/errorRegistry.js.map +1 -1
  74. package/dist/src/fieldExtraction.d.ts +125 -25
  75. package/dist/src/fieldExtraction.d.ts.map +1 -1
  76. package/dist/src/fieldExtraction.js +85 -16
  77. package/dist/src/fieldExtraction.js.map +1 -1
  78. package/dist/src/flagResolver.d.ts +75 -9
  79. package/dist/src/flagResolver.d.ts.map +1 -1
  80. package/dist/src/flagResolver.js +20 -4
  81. package/dist/src/flagResolver.js.map +1 -1
  82. package/dist/src/flagSemantics.d.ts +76 -1
  83. package/dist/src/flagSemantics.d.ts.map +1 -1
  84. package/dist/src/flagSemantics.js +66 -0
  85. package/dist/src/flagSemantics.js.map +1 -1
  86. package/dist/src/health/index.d.ts +87 -6
  87. package/dist/src/health/index.d.ts.map +1 -1
  88. package/dist/src/health/index.js +54 -6
  89. package/dist/src/health/index.js.map +1 -1
  90. package/dist/src/index.d.ts +12 -1
  91. package/dist/src/index.d.ts.map +1 -1
  92. package/dist/src/index.js +12 -1
  93. package/dist/src/index.js.map +1 -1
  94. package/dist/src/mviProjection.d.ts +42 -6
  95. package/dist/src/mviProjection.d.ts.map +1 -1
  96. package/dist/src/mviProjection.js +31 -5
  97. package/dist/src/mviProjection.js.map +1 -1
  98. package/dist/src/native-loader.d.ts +49 -0
  99. package/dist/src/native-loader.d.ts.map +1 -0
  100. package/dist/src/native-loader.js +56 -0
  101. package/dist/src/native-loader.js.map +1 -0
  102. package/dist/src/problemDetails.d.ts +70 -4
  103. package/dist/src/problemDetails.d.ts.map +1 -1
  104. package/dist/src/problemDetails.js +21 -3
  105. package/dist/src/problemDetails.js.map +1 -1
  106. package/dist/src/shutdown/index.d.ts +96 -7
  107. package/dist/src/shutdown/index.d.ts.map +1 -1
  108. package/dist/src/shutdown/index.js +72 -7
  109. package/dist/src/shutdown/index.js.map +1 -1
  110. package/dist/src/tokenEstimator.d.ts +97 -11
  111. package/dist/src/tokenEstimator.d.ts.map +1 -1
  112. package/dist/src/tokenEstimator.js +90 -11
  113. package/dist/src/tokenEstimator.js.map +1 -1
  114. package/dist/src/types.d.ts +467 -2
  115. package/dist/src/types.d.ts.map +1 -1
  116. package/dist/src/types.js +64 -0
  117. package/dist/src/types.js.map +1 -1
  118. package/dist/src/validateEnvelope.d.ts +59 -1
  119. package/dist/src/validateEnvelope.d.ts.map +1 -1
  120. package/dist/src/validateEnvelope.js +75 -9
  121. package/dist/src/validateEnvelope.js.map +1 -1
  122. package/dist/tsconfig.build.tsbuildinfo +1 -1
  123. package/lafs.md +3 -4
  124. package/package.json +6 -3
  125. package/dist/src/mcpAdapter.d.ts +0 -29
  126. package/dist/src/mcpAdapter.d.ts.map +0 -1
  127. package/dist/src/mcpAdapter.js +0 -286
  128. package/dist/src/mcpAdapter.js.map +0 -1
  129. package/schemas/v1/conformance-profiles.d.ts +0 -15
  130. package/schemas/v1/envelope.schema.d.ts +0 -14
  131. package/schemas/v1/error-registry.d.ts +0 -24
@@ -8,74 +8,201 @@
8
8
  */
9
9
  import type { RequestHandler } from 'express';
10
10
  /**
11
- * A2A Agent Provider information
11
+ * A2A Agent Provider information.
12
+ *
13
+ * @remarks
14
+ * Describes the organization that provides and maintains an A2A agent.
15
+ * Used within {@link AgentCard} to identify the service provider.
16
+ *
17
+ * @example
18
+ * ```typescript
19
+ * const provider: AgentProvider = {
20
+ * url: "https://example.com",
21
+ * organization: "Acme Corp"
22
+ * };
23
+ * ```
12
24
  */
13
25
  export interface AgentProvider {
14
- /** Organization URL */
26
+ /** Organization URL (must be a valid HTTPS URL) */
15
27
  url: string;
16
- /** Organization name */
28
+ /** Organization name (human-readable label) */
17
29
  organization: string;
18
30
  }
19
31
  /**
20
- * A2A Agent Capabilities
32
+ * A2A Agent Capabilities.
33
+ *
34
+ * @remarks
35
+ * Declares the runtime capabilities of an A2A agent, including streaming support,
36
+ * push notification handling, and registered protocol extensions.
37
+ *
38
+ * @example
39
+ * ```typescript
40
+ * const caps: AgentCapabilities = {
41
+ * streaming: true,
42
+ * pushNotifications: false,
43
+ * extendedAgentCard: false,
44
+ * extensions: []
45
+ * };
46
+ * ```
21
47
  */
22
48
  export interface AgentCapabilities {
23
- /** Supports streaming responses */
49
+ /**
50
+ * Supports streaming responses.
51
+ * @defaultValue `undefined` (treated as `false`)
52
+ */
24
53
  streaming?: boolean;
25
- /** Supports push notifications */
54
+ /**
55
+ * Supports push notifications.
56
+ * @defaultValue `undefined` (treated as `false`)
57
+ */
26
58
  pushNotifications?: boolean;
27
- /** Supports extended agent card */
59
+ /**
60
+ * Supports extended agent card.
61
+ * @defaultValue `undefined` (treated as `false`)
62
+ */
28
63
  extendedAgentCard?: boolean;
29
- /** Supported extensions */
64
+ /**
65
+ * Supported extensions declared by this agent.
66
+ * @defaultValue `undefined`
67
+ */
30
68
  extensions?: AgentExtension[];
31
69
  }
32
70
  /**
33
- * A2A Agent Extension declaration
71
+ * A2A Agent Extension declaration.
72
+ *
73
+ * @remarks
74
+ * Represents a protocol extension supported by the agent. Extensions use a URI
75
+ * as a globally-unique identifier and may carry extension-specific parameters.
76
+ *
77
+ * @example
78
+ * ```typescript
79
+ * const ext: AgentExtension = {
80
+ * uri: "https://lafs.dev/extensions/v1/lafs",
81
+ * description: "LAFS envelope protocol",
82
+ * required: false,
83
+ * params: { supportsContextLedger: true }
84
+ * };
85
+ * ```
34
86
  */
35
87
  export interface AgentExtension {
36
- /** Extension URI (unique identifier) */
88
+ /** Extension URI (globally-unique identifier) */
37
89
  uri: string;
38
- /** Human-readable description */
90
+ /** Human-readable description of what the extension provides */
39
91
  description: string;
40
- /** Whether the extension is required */
92
+ /** Whether the extension is required for interoperability */
41
93
  required: boolean;
42
- /** Extension-specific parameters */
94
+ /**
95
+ * Extension-specific parameters.
96
+ * @defaultValue `undefined`
97
+ */
43
98
  params?: Record<string, unknown>;
44
99
  }
45
100
  /**
46
- * A2A Agent Skill
101
+ * A2A Agent Skill.
102
+ *
103
+ * @remarks
104
+ * Describes a discrete capability exposed by the agent. Skills include metadata
105
+ * for discovery (tags, examples) and may override the agent-level I/O modes.
106
+ *
107
+ * @example
108
+ * ```typescript
109
+ * const skill: AgentSkill = {
110
+ * id: "envelope-processor",
111
+ * name: "Envelope Processor",
112
+ * description: "Validates and processes LAFS envelopes",
113
+ * tags: ["lafs", "envelope"],
114
+ * examples: ["Validate this envelope"],
115
+ * };
116
+ * ```
47
117
  */
48
118
  export interface AgentSkill {
49
- /** Skill unique identifier */
119
+ /** Skill unique identifier (kebab-case recommended) */
50
120
  id: string;
51
- /** Human-readable name */
121
+ /** Human-readable display name */
52
122
  name: string;
53
- /** Detailed description */
123
+ /** Detailed description of what the skill does */
54
124
  description: string;
55
- /** Keywords/tags for the skill */
125
+ /** Keywords/tags for discovery and categorization */
56
126
  tags: string[];
57
- /** Example prompts */
127
+ /**
128
+ * Example prompts that demonstrate typical usage.
129
+ * @defaultValue `undefined`
130
+ */
58
131
  examples?: string[];
59
- /** Supported input modes (overrides agent defaults) */
132
+ /**
133
+ * Supported input modes (overrides agent-level {@link AgentCard.defaultInputModes}).
134
+ * @defaultValue `undefined`
135
+ */
60
136
  inputModes?: string[];
61
- /** Supported output modes (overrides agent defaults) */
137
+ /**
138
+ * Supported output modes (overrides agent-level {@link AgentCard.defaultOutputModes}).
139
+ * @defaultValue `undefined`
140
+ */
62
141
  outputModes?: string[];
63
142
  }
64
143
  /**
65
- * Security scheme for authentication (OpenAPI 3.0 style)
144
+ * Security scheme for authentication (OpenAPI 3.0 style).
145
+ *
146
+ * @remarks
147
+ * Maps to the OpenAPI 3.0 Security Scheme Object. Used in {@link AgentCard.securitySchemes}
148
+ * to declare supported authentication mechanisms.
149
+ *
150
+ * @example
151
+ * ```typescript
152
+ * const scheme: SecurityScheme = {
153
+ * type: "http",
154
+ * scheme: "bearer",
155
+ * bearerFormat: "JWT",
156
+ * };
157
+ * ```
66
158
  */
67
159
  export interface SecurityScheme {
160
+ /** Authentication type per OpenAPI 3.0 */
68
161
  type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect';
162
+ /**
163
+ * Human-readable description of the scheme.
164
+ * @defaultValue `undefined`
165
+ */
69
166
  description?: string;
167
+ /**
168
+ * HTTP auth scheme name (e.g., `"bearer"`).
169
+ * @defaultValue `undefined`
170
+ */
70
171
  scheme?: string;
172
+ /**
173
+ * Bearer token format hint (e.g., `"JWT"`).
174
+ * @defaultValue `undefined`
175
+ */
71
176
  bearerFormat?: string;
72
177
  }
73
178
  /**
74
- * A2A v1.0 Agent Card - Standard format for agent discovery
75
- * Reference: specs/external/specification.md Section 5
179
+ * A2A v1.0 Agent Card - Standard format for agent discovery.
180
+ *
181
+ * @remarks
182
+ * The Agent Card is the primary discovery document for A2A v1.0. It is served
183
+ * at `/.well-known/agent-card.json` and describes the agent's identity,
184
+ * capabilities, skills, and security requirements.
185
+ * Reference: specs/external/specification.md Section 5.
186
+ *
187
+ * @example
188
+ * ```typescript
189
+ * const card: AgentCard = {
190
+ * name: "my-agent",
191
+ * description: "A LAFS-compliant agent",
192
+ * version: "1.0.0",
193
+ * url: "https://api.example.com",
194
+ * capabilities: { streaming: false },
195
+ * defaultInputModes: ["application/json"],
196
+ * defaultOutputModes: ["application/json"],
197
+ * skills: [],
198
+ * };
199
+ * ```
76
200
  */
77
201
  export interface AgentCard {
78
- /** JSON Schema URL */
202
+ /**
203
+ * JSON Schema URL for validation.
204
+ * @defaultValue `undefined`
205
+ */
79
206
  $schema?: string;
80
207
  /** Human-readable agent name */
81
208
  name: string;
@@ -85,78 +212,181 @@ export interface AgentCard {
85
212
  version: string;
86
213
  /** Base URL for A2A endpoints */
87
214
  url: string;
88
- /** Service provider information */
215
+ /**
216
+ * Service provider information.
217
+ * @defaultValue `undefined`
218
+ */
89
219
  provider?: AgentProvider;
90
- /** Agent capabilities */
220
+ /** Agent capabilities declaration */
91
221
  capabilities: AgentCapabilities;
92
- /** Supported input content types */
222
+ /** Supported input content types (MIME types) */
93
223
  defaultInputModes: string[];
94
- /** Supported output content types */
224
+ /** Supported output content types (MIME types) */
95
225
  defaultOutputModes: string[];
96
- /** Agent skills/capabilities */
226
+ /** Agent skills/capabilities for discovery */
97
227
  skills: AgentSkill[];
98
- /** Security authentication schemes */
228
+ /**
229
+ * Security authentication schemes (keyed by scheme name).
230
+ * @defaultValue `undefined`
231
+ */
99
232
  securitySchemes?: Record<string, SecurityScheme>;
100
- /** Required security schemes */
233
+ /**
234
+ * Required security scheme references (OpenAPI 3.0 format).
235
+ * @defaultValue `undefined`
236
+ */
101
237
  security?: Array<Record<string, string[]>>;
102
- /** Documentation URL */
238
+ /**
239
+ * Documentation URL for the agent.
240
+ * @defaultValue `undefined`
241
+ */
103
242
  documentationUrl?: string;
104
- /** Icon URL */
243
+ /**
244
+ * Icon URL for the agent.
245
+ * @defaultValue `undefined`
246
+ */
105
247
  iconUrl?: string;
106
248
  }
107
249
  /**
108
- * @deprecated Use AgentSkill instead
250
+ * Legacy capability descriptor.
251
+ *
252
+ * @deprecated Use {@link AgentSkill} instead.
253
+ *
254
+ * @remarks
255
+ * Retained for backward compatibility with pre-A2A discovery documents.
256
+ * Will be removed in v2.0.0.
109
257
  */
110
258
  export interface Capability {
259
+ /** Capability name */
111
260
  name: string;
261
+ /** Capability version */
112
262
  version: string;
263
+ /**
264
+ * Human-readable description.
265
+ * @defaultValue `undefined`
266
+ */
113
267
  description?: string;
268
+ /** Supported operations */
114
269
  operations: string[];
270
+ /**
271
+ * Whether this capability is optional.
272
+ * @defaultValue `undefined`
273
+ */
115
274
  optional?: boolean;
116
275
  }
117
276
  /**
118
- * @deprecated Use AgentCard instead
277
+ * Legacy service configuration.
278
+ *
279
+ * @deprecated Use {@link AgentCard} instead.
280
+ *
281
+ * @remarks
282
+ * Retained for backward compatibility with pre-A2A discovery documents.
283
+ * Will be removed in v2.0.0.
119
284
  */
120
285
  export interface ServiceConfig {
286
+ /** Service name */
121
287
  name: string;
288
+ /** Service version */
122
289
  version: string;
290
+ /**
291
+ * Human-readable description.
292
+ * @defaultValue `undefined`
293
+ */
123
294
  description?: string;
124
295
  }
125
296
  /**
126
- * @deprecated Will be removed in v2.0.0
297
+ * Legacy endpoint configuration.
298
+ *
299
+ * @deprecated Will be removed in v2.0.0.
300
+ *
301
+ * @remarks
302
+ * Retained for backward compatibility with pre-A2A discovery documents.
127
303
  */
128
304
  export interface EndpointConfig {
305
+ /** Envelope endpoint URL */
129
306
  envelope: string;
307
+ /**
308
+ * Context endpoint URL.
309
+ * @defaultValue `undefined`
310
+ */
130
311
  context?: string;
312
+ /** Discovery endpoint URL */
131
313
  discovery: string;
132
314
  }
133
315
  /**
134
- * @deprecated Use AgentCard instead
316
+ * Legacy discovery document format.
317
+ *
318
+ * @deprecated Use {@link AgentCard} instead.
319
+ *
320
+ * @remarks
321
+ * The pre-A2A discovery document format. Automatically generated from
322
+ * legacy config for backward compatibility. Will be removed in v2.0.0.
135
323
  */
136
324
  export interface DiscoveryDocument {
325
+ /** JSON Schema URL */
137
326
  $schema: string;
327
+ /** LAFS specification version */
138
328
  lafs_version: string;
329
+ /** Service configuration */
139
330
  service: ServiceConfig;
331
+ /** Declared capabilities */
140
332
  capabilities: Capability[];
333
+ /** Endpoint configuration */
141
334
  endpoints: EndpointConfig;
142
335
  }
143
336
  /**
144
- * Configuration for the discovery middleware (A2A v1.0 format)
337
+ * Configuration for the discovery middleware (A2A v1.0 format).
338
+ *
339
+ * @remarks
340
+ * Provide either `agent` (A2A v1.0) or the legacy `service`/`capabilities`/`endpoints`
341
+ * combination. The legacy fields are deprecated and will be removed in v2.0.0.
342
+ *
343
+ * @example
344
+ * ```typescript
345
+ * const config: DiscoveryConfig = {
346
+ * agent: {
347
+ * name: "my-agent",
348
+ * description: "Example",
349
+ * version: "1.0.0",
350
+ * url: "https://api.example.com",
351
+ * capabilities: { streaming: false },
352
+ * defaultInputModes: ["application/json"],
353
+ * defaultOutputModes: ["application/json"],
354
+ * skills: [],
355
+ * },
356
+ * cacheMaxAge: 3600,
357
+ * };
358
+ * ```
145
359
  */
146
360
  export interface DiscoveryConfig {
147
- /** Agent information (required for A2A v1.0; omit only with legacy 'service') */
361
+ /**
362
+ * Agent information (required for A2A v1.0; omit only with legacy `service`).
363
+ * @defaultValue `undefined`
364
+ */
148
365
  agent?: Omit<AgentCard, '$schema'>;
149
- /** Base URL for constructing absolute URLs */
366
+ /**
367
+ * Base URL for constructing absolute URLs.
368
+ * @defaultValue `undefined`
369
+ */
150
370
  baseUrl?: string;
151
- /** Cache duration in seconds (default: 3600) */
371
+ /**
372
+ * Cache duration in seconds.
373
+ * @defaultValue `3600`
374
+ */
152
375
  cacheMaxAge?: number;
153
- /** Schema URL override */
376
+ /**
377
+ * Schema URL override.
378
+ * @defaultValue `undefined`
379
+ */
154
380
  schemaUrl?: string;
155
- /** Optional custom headers */
381
+ /**
382
+ * Optional custom response headers.
383
+ * @defaultValue `undefined`
384
+ */
156
385
  headers?: Record<string, string>;
157
386
  /**
158
387
  * Automatically include LAFS as an A2A extension in Agent Card.
159
388
  * Pass `true` for defaults, or an object to customize parameters.
389
+ * @defaultValue `undefined`
160
390
  */
161
391
  autoIncludeLafsExtension?: boolean | {
162
392
  required?: boolean;
@@ -164,15 +394,21 @@ export interface DiscoveryConfig {
164
394
  supportsTokenBudgets?: boolean;
165
395
  };
166
396
  /**
167
- * @deprecated Use 'agent' instead
397
+ * Legacy service configuration.
398
+ * @deprecated Use `agent` instead.
399
+ * @defaultValue `undefined`
168
400
  */
169
401
  service?: ServiceConfig;
170
402
  /**
171
- * @deprecated Use 'agent.skills' instead
403
+ * Legacy capabilities list.
404
+ * @deprecated Use `agent.skills` instead.
405
+ * @defaultValue `undefined`
172
406
  */
173
407
  capabilities?: Capability[];
174
408
  /**
175
- * @deprecated Use 'agent.url' and individual endpoints
409
+ * Legacy endpoint URLs.
410
+ * @deprecated Use `agent.url` and individual endpoints.
411
+ * @defaultValue `undefined`
176
412
  */
177
413
  endpoints?: {
178
414
  envelope: string;
@@ -180,39 +416,67 @@ export interface DiscoveryConfig {
180
416
  discovery?: string;
181
417
  };
182
418
  /**
183
- * @deprecated Use 'agent.version' instead
419
+ * Legacy LAFS version override.
420
+ * @deprecated Use `agent.version` instead.
421
+ * @defaultValue `undefined`
184
422
  */
185
423
  lafsVersion?: string;
186
424
  }
187
425
  /**
188
- * Discovery middleware options
426
+ * Discovery middleware options.
427
+ *
428
+ * @remarks
429
+ * Controls path routing, legacy support, and caching behavior
430
+ * for the discovery middleware.
431
+ *
432
+ * @example
433
+ * ```typescript
434
+ * const options: DiscoveryMiddlewareOptions = {
435
+ * path: "/.well-known/agent-card.json",
436
+ * enableEtag: true,
437
+ * };
438
+ * ```
189
439
  */
190
440
  export interface DiscoveryMiddlewareOptions {
191
441
  /**
192
- * Primary path to serve Agent Card (default: /.well-known/agent-card.json)
442
+ * Primary path to serve Agent Card.
443
+ * @defaultValue `"/.well-known/agent-card.json"`
193
444
  */
194
445
  path?: string;
195
446
  /**
196
- * Legacy path for backward compatibility (default: /.well-known/lafs.json)
197
- * @deprecated Will be removed in v2.0.0
447
+ * Legacy path for backward compatibility.
448
+ * @deprecated Will be removed in v2.0.0.
449
+ * @defaultValue `"/.well-known/lafs.json"`
198
450
  */
199
451
  legacyPath?: string;
200
- /** Enable legacy path support (default: true) */
452
+ /**
453
+ * Enable legacy path support.
454
+ * @defaultValue `true` (disabled when a custom `path` is set)
455
+ */
201
456
  enableLegacyPath?: boolean;
202
- /** Enable HEAD requests (default: true) */
457
+ /**
458
+ * Enable HEAD requests.
459
+ * @defaultValue `true`
460
+ */
203
461
  enableHead?: boolean;
204
- /** Enable ETag caching (default: true) */
462
+ /**
463
+ * Enable ETag caching.
464
+ * @defaultValue `true`
465
+ */
205
466
  enableEtag?: boolean;
206
467
  }
207
468
  /**
208
- * Create Express middleware for serving A2A Agent Card
209
- *
210
- * Serves A2A-compliant Agent Card at /.well-known/agent-card.json
211
- * Maintains backward compatibility with legacy /.well-known/lafs.json
469
+ * Create Express middleware for serving A2A Agent Card.
212
470
  *
213
471
  * @param config - Discovery configuration (A2A v1.0 format)
214
- * @param options - Middleware options
215
- * @returns Express RequestHandler
472
+ * @param options - Middleware options for path routing and caching
473
+ * @returns Express RequestHandler that serves the Agent Card
474
+ *
475
+ * @remarks
476
+ * Serves an A2A-compliant Agent Card at `/.well-known/agent-card.json`.
477
+ * Maintains backward compatibility with the legacy `/.well-known/lafs.json`
478
+ * path (with deprecation warnings). Supports ETag-based conditional requests,
479
+ * HEAD requests, and configurable cache headers.
216
480
  *
217
481
  * @example
218
482
  * ```typescript
@@ -249,10 +513,27 @@ export interface DiscoveryMiddlewareOptions {
249
513
  */
250
514
  export declare function discoveryMiddleware(config: DiscoveryConfig, options?: DiscoveryMiddlewareOptions): RequestHandler;
251
515
  /**
252
- * Fastify plugin for A2A Agent Card discovery
516
+ * Fastify plugin for A2A Agent Card discovery.
253
517
  *
254
518
  * @param fastify - Fastify instance
255
- * @param options - Plugin options
519
+ * @param options - Plugin options containing `config` and optional `path`
520
+ * @returns Promise that resolves when the plugin is registered
521
+ *
522
+ * @remarks
523
+ * Registers a route on the Fastify instance to serve the A2A Agent Card
524
+ * with proper caching headers. The actual route registration depends on
525
+ * the Fastify API; this provides a type-safe plugin signature.
526
+ *
527
+ * @example
528
+ * ```typescript
529
+ * import Fastify from "fastify";
530
+ * import { discoveryFastifyPlugin } from "@cleocode/lafs/discovery";
531
+ *
532
+ * const app = Fastify();
533
+ * app.register(discoveryFastifyPlugin, {
534
+ * config: { agent: { name: "my-agent", ... } },
535
+ * });
536
+ * ```
256
537
  */
257
538
  export declare function discoveryFastifyPlugin(fastify: unknown, options: {
258
539
  config: DiscoveryConfig;
@@ -1 +1 @@
1
- {"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/discovery.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/discovery.ts"],"names":[],"mappings":"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"}