@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
@@ -4,6 +4,12 @@
4
4
  * State machine enforcement, task CRUD, and LAFS integration
5
5
  * for A2A Protocol v1.0+ compliance.
6
6
  *
7
+ * @remarks
8
+ * Implements the A2A task state machine with valid transitions, terminal
9
+ * state immutability, and context-based task grouping. Provides an
10
+ * in-memory TaskManager for managing task lifecycle and LAFS envelope
11
+ * attachment.
12
+ *
7
13
  * Reference: A2A spec Section 6 (Task Lifecycle)
8
14
  */
9
15
  import { createLafsArtifact } from './bridge.js';
@@ -52,27 +58,90 @@ export const VALID_TRANSITIONS = new Map([
52
58
  // ============================================================================
53
59
  // State Functions
54
60
  // ============================================================================
55
- /** Check if a transition from one state to another is valid */
61
+ /**
62
+ * Check if a transition from one state to another is valid.
63
+ *
64
+ * @remarks
65
+ * Looks up the `from` state in the VALID_TRANSITIONS adjacency map and
66
+ * checks whether `to` is in the allowed set.
67
+ *
68
+ * @param from - Current task state
69
+ * @param to - Desired target state
70
+ * @returns True if the transition is allowed by the state machine
71
+ *
72
+ * @example
73
+ * ```typescript
74
+ * if (!isValidTransition('submitted', 'completed')) {
75
+ * throw new Error('Cannot go directly from submitted to completed');
76
+ * }
77
+ * ```
78
+ */
56
79
  export function isValidTransition(from, to) {
57
80
  const allowed = VALID_TRANSITIONS.get(from);
58
81
  return allowed ? allowed.has(to) : false;
59
82
  }
60
- /** Check if a state is terminal (no further transitions allowed) */
83
+ /**
84
+ * Check if a state is terminal (no further transitions allowed).
85
+ *
86
+ * @remarks
87
+ * Terminal states are `completed`, `failed`, `canceled`, and `rejected`.
88
+ *
89
+ * @param state - Task state to check
90
+ * @returns True if the state is terminal
91
+ *
92
+ * @example
93
+ * ```typescript
94
+ * if (isTerminalState(task.status.state)) {
95
+ * console.log('Task has reached a final state');
96
+ * }
97
+ * ```
98
+ */
61
99
  export function isTerminalState(state) {
62
100
  return TERMINAL_STATES.has(state);
63
101
  }
64
- /** Check if a state is interrupted (paused awaiting input) */
102
+ /**
103
+ * Check if a state is interrupted (paused awaiting input).
104
+ *
105
+ * @remarks
106
+ * Interrupted states are `input-required` and `auth-required`.
107
+ *
108
+ * @param state - Task state to check
109
+ * @returns True if the state indicates the task is waiting for external input
110
+ *
111
+ * @example
112
+ * ```typescript
113
+ * if (isInterruptedState(task.status.state)) {
114
+ * promptUserForInput(task);
115
+ * }
116
+ * ```
117
+ */
65
118
  export function isInterruptedState(state) {
66
119
  return INTERRUPTED_STATES.has(state);
67
120
  }
68
121
  // ============================================================================
69
122
  // Error Classes
70
123
  // ============================================================================
71
- /** Thrown when attempting an invalid state transition */
124
+ /**
125
+ * Thrown when attempting an invalid state transition.
126
+ *
127
+ * @remarks
128
+ * Captures the task ID, source state, and target state so callers can
129
+ * determine which transition was rejected.
130
+ */
72
131
  export class InvalidStateTransitionError extends Error {
132
+ /** ID of the task that failed the transition */
73
133
  taskId;
134
+ /** State the task was in when the transition was attempted */
74
135
  fromState;
136
+ /** State the task was being transitioned to */
75
137
  toState;
138
+ /**
139
+ * Create an InvalidStateTransitionError.
140
+ *
141
+ * @param taskId - ID of the task that failed the transition
142
+ * @param fromState - Current state of the task
143
+ * @param toState - Desired target state that was rejected
144
+ */
76
145
  constructor(taskId, fromState, toState) {
77
146
  super(`Invalid transition for task ${taskId}: ${fromState} -> ${toState}`);
78
147
  this.name = 'InvalidStateTransitionError';
@@ -81,10 +150,24 @@ export class InvalidStateTransitionError extends Error {
81
150
  this.toState = toState;
82
151
  }
83
152
  }
84
- /** Thrown when attempting to modify a task in a terminal state */
153
+ /**
154
+ * Thrown when attempting to modify a task in a terminal state.
155
+ *
156
+ * @remarks
157
+ * Tasks in terminal states (`completed`, `failed`, `canceled`, `rejected`)
158
+ * are immutable and cannot be modified further.
159
+ */
85
160
  export class TaskImmutabilityError extends Error {
161
+ /** ID of the task that cannot be modified */
86
162
  taskId;
163
+ /** Terminal state the task is in */
87
164
  terminalState;
165
+ /**
166
+ * Create a TaskImmutabilityError.
167
+ *
168
+ * @param taskId - ID of the task in terminal state
169
+ * @param terminalState - The terminal state preventing modification
170
+ */
88
171
  constructor(taskId, terminalState) {
89
172
  super(`Task ${taskId} is in terminal state ${terminalState} and cannot be modified`);
90
173
  this.name = 'TaskImmutabilityError';
@@ -92,18 +175,43 @@ export class TaskImmutabilityError extends Error {
92
175
  this.terminalState = terminalState;
93
176
  }
94
177
  }
95
- /** Thrown when a task is not found */
178
+ /**
179
+ * Thrown when a task is not found.
180
+ *
181
+ * @remarks
182
+ * Indicates a lookup by task ID failed because no task with that ID exists
183
+ * in the TaskManager's store.
184
+ */
96
185
  export class TaskNotFoundError extends Error {
186
+ /** ID of the task that was not found */
97
187
  taskId;
188
+ /**
189
+ * Create a TaskNotFoundError.
190
+ *
191
+ * @param taskId - ID of the task that was not found
192
+ */
98
193
  constructor(taskId) {
99
194
  super(`Task not found: ${taskId}`);
100
195
  this.name = 'TaskNotFoundError';
101
196
  this.taskId = taskId;
102
197
  }
103
198
  }
104
- /** Thrown when a refinement/follow-up task references invalid parent tasks */
199
+ /**
200
+ * Thrown when a refinement/follow-up task references invalid parent tasks.
201
+ *
202
+ * @remarks
203
+ * Occurs when referenced tasks do not exist or belong to a different
204
+ * context than the refinement task.
205
+ */
105
206
  export class TaskRefinementError extends Error {
207
+ /** IDs of the referenced tasks that caused the error */
106
208
  referenceTaskIds;
209
+ /**
210
+ * Create a TaskRefinementError.
211
+ *
212
+ * @param message - Descriptive error message
213
+ * @param referenceTaskIds - IDs of the invalid reference tasks
214
+ */
107
215
  constructor(message, referenceTaskIds) {
108
216
  super(message);
109
217
  this.name = 'TaskRefinementError';
@@ -122,12 +230,34 @@ function generateId() {
122
230
  }
123
231
  /**
124
232
  * In-memory task manager implementing A2A task lifecycle.
233
+ *
234
+ * @remarks
125
235
  * Enforces valid state transitions and terminal state immutability.
236
+ * Tasks are indexed by both ID and context ID for efficient lookup.
237
+ * All returned Task objects are deep clones to prevent external mutation.
126
238
  */
127
239
  export class TaskManager {
240
+ /** Map of task ID to Task object */
128
241
  tasks = new Map();
242
+ /** Index mapping context ID to set of task IDs */
129
243
  contextIndex = new Map();
130
- /** Create a new task in the submitted state */
244
+ /**
245
+ * Create a new task in the submitted state.
246
+ *
247
+ * @remarks
248
+ * Generates a UUID for the task and resolves the context ID from options
249
+ * or referenced tasks. Validates that all reference tasks exist and share
250
+ * the same context.
251
+ *
252
+ * @param options - Task creation options including context, metadata, and references
253
+ * @returns Deep clone of the newly created task
254
+ *
255
+ * @example
256
+ * ```typescript
257
+ * const manager = new TaskManager();
258
+ * const task = manager.createTask({ contextId: 'ctx-1', metadata: { source: 'api' } });
259
+ * ```
260
+ */
131
261
  createTask(options) {
132
262
  const id = generateId();
133
263
  const resolvedContextId = options?.contextId ??
@@ -161,7 +291,23 @@ export class TaskManager {
161
291
  contextTasks.add(id);
162
292
  return structuredClone(task);
163
293
  }
164
- /** Create a refinement/follow-up task referencing existing task(s). */
294
+ /**
295
+ * Create a refinement/follow-up task referencing existing task(s).
296
+ *
297
+ * @remarks
298
+ * Delegates to {@link TaskManager.createTask} with the provided reference
299
+ * task IDs. The context ID is automatically resolved from the first
300
+ * referenced task.
301
+ *
302
+ * @param referenceTaskIds - IDs of parent tasks to reference
303
+ * @param options - Additional task creation options (excluding referenceTaskIds)
304
+ * @returns Deep clone of the newly created refinement task
305
+ *
306
+ * @example
307
+ * ```typescript
308
+ * const refined = manager.createRefinedTask(['task-1'], { parallelFollowUp: true });
309
+ * ```
310
+ */
165
311
  createRefinedTask(referenceTaskIds, options) {
166
312
  return this.createTask({
167
313
  ...options,
@@ -169,7 +315,22 @@ export class TaskManager {
169
315
  parallelFollowUp: options?.parallelFollowUp,
170
316
  });
171
317
  }
172
- /** Get a task by ID. Throws TaskNotFoundError if not found. */
318
+ /**
319
+ * Get a task by ID.
320
+ *
321
+ * @remarks
322
+ * Returns a deep clone of the task to prevent external mutation.
323
+ *
324
+ * @param taskId - ID of the task to retrieve
325
+ * @returns Deep clone of the requested task
326
+ * @throws {@link TaskNotFoundError} if no task with the given ID exists
327
+ *
328
+ * @example
329
+ * ```typescript
330
+ * const task = manager.getTask('some-task-id');
331
+ * console.log(task.status.state);
332
+ * ```
333
+ */
173
334
  getTask(taskId) {
174
335
  const task = this.tasks.get(taskId);
175
336
  if (!task) {
@@ -177,7 +338,25 @@ export class TaskManager {
177
338
  }
178
339
  return structuredClone(task);
179
340
  }
180
- /** List tasks with optional filtering and pagination */
341
+ /**
342
+ * List tasks with optional filtering and pagination.
343
+ *
344
+ * @remarks
345
+ * Supports filtering by context ID and state, with cursor-based
346
+ * pagination using the last seen task ID as a page token. Results
347
+ * are sorted by task ID for deterministic ordering.
348
+ *
349
+ * @param options - Filtering and pagination options
350
+ * @returns Paginated result with tasks and optional next page token
351
+ *
352
+ * @example
353
+ * ```typescript
354
+ * const result = manager.listTasks({ contextId: 'ctx-1', state: 'working', limit: 10 });
355
+ * for (const task of result.tasks) {
356
+ * console.log(task.id, task.status.state);
357
+ * }
358
+ * ```
359
+ */
181
360
  listTasks(options) {
182
361
  let taskIds;
183
362
  if (options?.contextId) {
@@ -213,8 +392,23 @@ export class TaskManager {
213
392
  }
214
393
  /**
215
394
  * Update task status. Enforces valid transitions and terminal state immutability.
216
- * @throws InvalidStateTransitionError if the transition is not valid
217
- * @throws TaskImmutabilityError if the task is in a terminal state
395
+ *
396
+ * @remarks
397
+ * Validates that the transition is allowed by the state machine before
398
+ * applying. An optional message can be attached to the new status.
399
+ *
400
+ * @param taskId - ID of the task to update
401
+ * @param state - New state to transition to
402
+ * @param message - Optional message to attach to the status update
403
+ * @returns Deep clone of the updated task
404
+ * @throws {@link InvalidStateTransitionError} if the transition is not valid
405
+ * @throws {@link TaskImmutabilityError} if the task is in a terminal state
406
+ * @throws {@link TaskNotFoundError} if the task does not exist
407
+ *
408
+ * @example
409
+ * ```typescript
410
+ * const updated = manager.updateTaskStatus('task-1', 'working');
411
+ * ```
218
412
  */
219
413
  updateTaskStatus(taskId, state, message) {
220
414
  const task = this.tasks.get(taskId);
@@ -238,7 +432,22 @@ export class TaskManager {
238
432
  }
239
433
  /**
240
434
  * Add an artifact to a task.
241
- * @throws TaskImmutabilityError if the task is in a terminal state
435
+ *
436
+ * @remarks
437
+ * Appends the artifact to the task's artifacts array. The task must
438
+ * not be in a terminal state.
439
+ *
440
+ * @param taskId - ID of the task to add the artifact to
441
+ * @param artifact - Artifact to add
442
+ * @returns Deep clone of the updated task
443
+ * @throws {@link TaskImmutabilityError} if the task is in a terminal state
444
+ * @throws {@link TaskNotFoundError} if the task does not exist
445
+ *
446
+ * @example
447
+ * ```typescript
448
+ * const artifact = createLafsArtifact(envelope);
449
+ * manager.addArtifact('task-1', artifact);
450
+ * ```
242
451
  */
243
452
  addArtifact(taskId, artifact) {
244
453
  const task = this.tasks.get(taskId);
@@ -256,7 +465,21 @@ export class TaskManager {
256
465
  }
257
466
  /**
258
467
  * Add a message to task history.
259
- * @throws TaskImmutabilityError if the task is in a terminal state
468
+ *
469
+ * @remarks
470
+ * Appends the message to the task's history array. The task must
471
+ * not be in a terminal state.
472
+ *
473
+ * @param taskId - ID of the task to add the message to
474
+ * @param message - Message to add to history
475
+ * @returns Deep clone of the updated task
476
+ * @throws {@link TaskImmutabilityError} if the task is in a terminal state
477
+ * @throws {@link TaskNotFoundError} if the task does not exist
478
+ *
479
+ * @example
480
+ * ```typescript
481
+ * manager.addHistory('task-1', { role: 'agent', parts: [{ kind: 'text', text: 'Done' }] });
482
+ * ```
260
483
  */
261
484
  addHistory(taskId, message) {
262
485
  const task = this.tasks.get(taskId);
@@ -272,18 +495,62 @@ export class TaskManager {
272
495
  task.history.push(message);
273
496
  return structuredClone(task);
274
497
  }
275
- /** Cancel a task by transitioning to canceled state */
498
+ /**
499
+ * Cancel a task by transitioning to canceled state.
500
+ *
501
+ * @remarks
502
+ * Convenience wrapper around {@link TaskManager.updateTaskStatus} with `'canceled'`.
503
+ *
504
+ * @param taskId - ID of the task to cancel
505
+ * @returns Deep clone of the canceled task
506
+ * @throws {@link InvalidStateTransitionError} if cancellation is not valid from the current state
507
+ * @throws {@link TaskImmutabilityError} if the task is already in a terminal state
508
+ *
509
+ * @example
510
+ * ```typescript
511
+ * const canceled = manager.cancelTask('task-1');
512
+ * ```
513
+ */
276
514
  cancelTask(taskId) {
277
515
  return this.updateTaskStatus(taskId, 'canceled');
278
516
  }
279
- /** Get all tasks in a given context */
517
+ /**
518
+ * Get all tasks in a given context.
519
+ *
520
+ * @remarks
521
+ * Returns deep clones of all tasks sharing the specified context ID.
522
+ *
523
+ * @param contextId - Context ID to look up
524
+ * @returns Array of deep-cloned tasks in the context, or empty array if none
525
+ *
526
+ * @example
527
+ * ```typescript
528
+ * const tasks = manager.getTasksByContext('ctx-1');
529
+ * ```
530
+ */
280
531
  getTasksByContext(contextId) {
281
532
  const taskIds = this.contextIndex.get(contextId);
282
533
  if (!taskIds)
283
534
  return [];
284
535
  return [...taskIds].map((id) => structuredClone(this.tasks.get(id)));
285
536
  }
286
- /** Check if a task is in a terminal state */
537
+ /**
538
+ * Check if a task is in a terminal state.
539
+ *
540
+ * @remarks
541
+ * Retrieves the task and checks its current state against the terminal states set.
542
+ *
543
+ * @param taskId - ID of the task to check
544
+ * @returns True if the task is in a terminal state
545
+ * @throws {@link TaskNotFoundError} if the task does not exist
546
+ *
547
+ * @example
548
+ * ```typescript
549
+ * if (manager.isTerminal('task-1')) {
550
+ * console.log('Task is finished');
551
+ * }
552
+ * ```
553
+ */
287
554
  isTerminal(taskId) {
288
555
  const task = this.tasks.get(taskId);
289
556
  if (!task) {
@@ -291,6 +558,7 @@ export class TaskManager {
291
558
  }
292
559
  return isTerminalState(task.status.state);
293
560
  }
561
+ /** Derive a contextId from the first referenced task, if any reference tasks are provided. */
294
562
  resolveContextForReferenceTasks(referenceTaskIds) {
295
563
  if (!referenceTaskIds || referenceTaskIds.length === 0) {
296
564
  return undefined;
@@ -302,6 +570,7 @@ export class TaskManager {
302
570
  const first = this.tasks.get(firstId);
303
571
  return first?.contextId;
304
572
  }
573
+ /** Validate that all referenced tasks exist and share the same contextId. */
305
574
  validateReferenceTasks(referenceTaskIds, contextId) {
306
575
  if (referenceTaskIds.length === 0) {
307
576
  return;
@@ -322,7 +591,21 @@ export class TaskManager {
322
591
  // ============================================================================
323
592
  /**
324
593
  * Attach a LAFS envelope as an artifact to an A2A task.
325
- * Uses createLafsArtifact() from bridge.ts to wrap the envelope.
594
+ *
595
+ * @remarks
596
+ * Uses {@link createLafsArtifact} from bridge.ts to wrap the envelope
597
+ * in a properly formatted A2A artifact, then adds it to the task.
598
+ *
599
+ * @param manager - TaskManager instance managing the task
600
+ * @param taskId - ID of the task to attach the envelope to
601
+ * @param envelope - LAFS envelope to attach as an artifact
602
+ * @returns Deep clone of the updated task with the new artifact
603
+ *
604
+ * @example
605
+ * ```typescript
606
+ * const envelope: LAFSEnvelope = { success: true, result: { data: 'ok' }, error: null, _meta: meta };
607
+ * const updated = attachLafsEnvelope(manager, 'task-1', envelope);
608
+ * ```
326
609
  */
327
610
  export function attachLafsEnvelope(manager, taskId, envelope) {
328
611
  const artifact = createLafsArtifact(envelope);
@@ -1 +1 @@
1
- {"version":3,"file":"task-lifecycle.js","sourceRoot":"","sources":["../../../src/a2a/task-lifecycle.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"task-lifecycle.js","sourceRoot":"","sources":["../../../src/a2a/task-lifecycle.ts"],"names":[],"mappings":"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"}
@@ -7,28 +7,55 @@
7
7
  import { TokenEstimator } from './tokenEstimator.js';
8
8
  import type { BudgetEnforcementOptions, BudgetEnforcementResult, LAFSEnvelope, TokenEstimate } from './types.js';
9
9
  /**
10
- * Budget exceeded error code from LAFS error registry
10
+ * Budget exceeded error code from LAFS error registry.
11
+ *
12
+ * @remarks
13
+ * Used as the `code` field in {@link LAFSError} when a response exceeds
14
+ * its declared MVI token budget.
11
15
  */
12
16
  declare const BUDGET_EXCEEDED_CODE = "E_MVI_BUDGET_EXCEEDED";
13
17
  /**
14
18
  * Apply budget enforcement to an envelope.
15
19
  *
16
20
  * @param envelope - The LAFS envelope to check
17
- * @param budget - Maximum allowed tokens
18
- * @param options - Budget enforcement options
19
- * @returns Enforce result with potentially modified envelope
21
+ * @param budget - Maximum allowed token count
22
+ * @param options - Budget enforcement options (truncation, callbacks)
23
+ * @returns Enforcement result with the (possibly modified) envelope, budget status, and token estimates
24
+ *
25
+ * @remarks
26
+ * When the envelope is within budget, the token estimate is attached to metadata.
27
+ * When exceeded, behavior depends on `options.truncateOnExceed`: if enabled,
28
+ * truncation is attempted first; otherwise, the result is replaced with a
29
+ * budget-exceeded error. The `onBudgetExceeded` callback fires before truncation.
30
+ *
31
+ * @example
32
+ * ```typescript
33
+ * const result = applyBudgetEnforcement(envelope, 1000, { truncateOnExceed: true });
34
+ * if (!result.withinBudget) {
35
+ * console.warn("Budget exceeded:", result.estimatedTokens);
36
+ * }
37
+ * ```
20
38
  */
21
39
  export declare function applyBudgetEnforcement(envelope: LAFSEnvelope, budget: number, options?: BudgetEnforcementOptions): BudgetEnforcementResult;
22
40
  /**
23
- * Type for middleware function
41
+ * Type for envelope middleware function.
42
+ *
43
+ * @remarks
44
+ * Middleware functions receive an envelope and a `next` callback, enabling
45
+ * pre- and post-processing of LAFS envelopes in a pipeline.
24
46
  */
25
47
  type EnvelopeMiddleware = (envelope: LAFSEnvelope, next: () => LAFSEnvelope | Promise<LAFSEnvelope>) => Promise<LAFSEnvelope> | LAFSEnvelope;
26
48
  /**
27
49
  * Create a budget enforcement middleware function.
28
50
  *
29
- * @param budget - Maximum allowed tokens for response
30
- * @param options - Budget enforcement options
31
- * @returns Middleware function that enforces budget
51
+ * @param budget - Maximum allowed token count for the response
52
+ * @param options - Budget enforcement options (truncation, callbacks)
53
+ * @returns Async middleware function that enforces the token budget
54
+ *
55
+ * @remarks
56
+ * Wraps the next handler in the chain, applying {@link applyBudgetEnforcement}
57
+ * to its output. The returned envelope may be truncated or replaced with an
58
+ * error depending on the enforcement result.
32
59
  *
33
60
  * @example
34
61
  * ```typescript
@@ -41,8 +68,20 @@ export declare function withBudget(budget: number, options?: BudgetEnforcementOp
41
68
  * Check if an envelope has exceeded its budget without modifying it.
42
69
  *
43
70
  * @param envelope - The LAFS envelope to check
44
- * @param budget - Maximum allowed tokens
45
- * @returns Budget check result
71
+ * @param budget - Maximum allowed token count
72
+ * @returns Object with `exceeded` flag, `estimated` token count, and `remaining` budget
73
+ *
74
+ * @remarks
75
+ * A read-only budget check that does not alter the envelope. Useful for
76
+ * pre-flight checks or logging before deciding how to handle overages.
77
+ *
78
+ * @example
79
+ * ```typescript
80
+ * const { exceeded, estimated, remaining } = checkBudget(envelope, 500);
81
+ * if (exceeded) {
82
+ * console.warn(`Over budget by ${estimated - 500} tokens`);
83
+ * }
84
+ * ```
46
85
  */
47
86
  export declare function checkBudget(envelope: LAFSEnvelope, budget: number): {
48
87
  exceeded: boolean;
@@ -52,19 +91,38 @@ export declare function checkBudget(envelope: LAFSEnvelope, budget: number): {
52
91
  /**
53
92
  * Synchronous version of withBudget for non-async contexts.
54
93
  *
55
- * @param budget - Maximum allowed tokens for response
56
- * @param options - Budget enforcement options
57
- * @returns Middleware function that enforces budget synchronously
94
+ * @param budget - Maximum allowed token count for the response
95
+ * @param options - Budget enforcement options (truncation, callbacks)
96
+ * @returns Synchronous middleware function that enforces the token budget
97
+ *
98
+ * @remarks
99
+ * Identical to {@link withBudget} but operates synchronously. Use this when the
100
+ * next handler in the chain is guaranteed to return synchronously.
101
+ *
102
+ * @example
103
+ * ```typescript
104
+ * const middleware = withBudgetSync(500);
105
+ * const result = middleware(envelope, () => nextEnvelope);
106
+ * ```
58
107
  */
59
108
  export declare function withBudgetSync(budget: number, options?: BudgetEnforcementOptions): (envelope: LAFSEnvelope, next: () => LAFSEnvelope) => LAFSEnvelope;
60
109
  /**
61
110
  * Higher-order function that wraps a handler with budget enforcement.
62
111
  *
63
112
  * @param handler - The handler function to wrap
113
+ * @typeParam TArgs - Tuple type representing the handler's parameter list
114
+ * @typeParam TResult - Return type of the handler, must extend LAFSEnvelope
115
+ * @param handler - The handler function to wrap with budget enforcement
64
116
  * @param budget - Maximum allowed tokens
65
117
  * @param options - Budget enforcement options
66
118
  * @returns Wrapped handler with budget enforcement
67
119
  *
120
+ * @remarks
121
+ * The returned function has the same parameter signature as the original handler
122
+ * but always returns a `Promise<LAFSEnvelope>`. When the budget is exceeded and
123
+ * `truncateOnExceed` is enabled, the envelope is truncated to fit; otherwise an
124
+ * `E_MVI_BUDGET_EXCEEDED` error envelope is returned.
125
+ *
68
126
  * @example
69
127
  * ```typescript
70
128
  * const myHandler = async (request: Request) => ({ success: true, result: { data } });
@@ -75,7 +133,23 @@ export declare function withBudgetSync(budget: number, options?: BudgetEnforceme
75
133
  export declare function wrapWithBudget<TArgs extends unknown[], TResult extends LAFSEnvelope>(handler: (...args: TArgs) => TResult | Promise<TResult>, budget: number, options?: BudgetEnforcementOptions): (...args: TArgs) => Promise<LAFSEnvelope>;
76
134
  /**
77
135
  * Compose multiple middleware functions into a single middleware.
78
- * Middleware is executed in order (left to right).
136
+ *
137
+ * @param middlewares - Middleware functions to compose (executed left to right)
138
+ * @returns A single middleware function that chains all provided middlewares
139
+ *
140
+ * @remarks
141
+ * Middleware is executed in array order (left to right). Each middleware receives
142
+ * the envelope and a `next` function that invokes the subsequent middleware.
143
+ * The final middleware's `next` call invokes the original terminal handler.
144
+ *
145
+ * @example
146
+ * ```typescript
147
+ * const pipeline = composeMiddleware(
148
+ * withBudget(1000),
149
+ * loggingMiddleware,
150
+ * );
151
+ * const result = await pipeline(envelope, () => finalEnvelope);
152
+ * ```
79
153
  */
80
154
  export declare function composeMiddleware(...middlewares: EnvelopeMiddleware[]): EnvelopeMiddleware;
81
155
  export type { BudgetEnforcementOptions, BudgetEnforcementResult, TokenEstimate };
@@ -1 +1 @@
1
- {"version":3,"file":"budgetEnforcement.d.ts","sourceRoot":"","sources":["../../src/budgetEnforcement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACvB,YAAY,EAIZ,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,QAAA,MAAM,oBAAoB,0BAA0B,CAAC;AAwLrD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAiFzB;AAED;;GAEG;AACH,KAAK,kBAAkB,GAAG,CACxB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,KAC7C,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAapB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAS7D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,YAAY,KAAK,YAAY,CAMpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,SAAS,YAAY,EAClF,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACvD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,YAAY,CAAC,CAM3C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,WAAW,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,CAsB1F;AAGD,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,aAAa,EAAE,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,CAAC"}
1
+ {"version":3,"file":"budgetEnforcement.d.ts","sourceRoot":"","sources":["../../src/budgetEnforcement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACvB,YAAY,EAIZ,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,QAAA,MAAM,oBAAoB,0BAA0B,CAAC;AAmOrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAiFzB;AAED;;;;;;GAMG;AACH,KAAK,kBAAkB,GAAG,CACxB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,KAC7C,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,kBAAkB,CAapB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAS7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,YAAY,KAAK,YAAY,CAMpE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,SAAS,YAAY,EAClF,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACvD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,YAAY,CAAC,CAM3C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,WAAW,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,CAsB1F;AAGD,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,aAAa,EAAE,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,CAAC"}