@cleocode/lafs 2026.4.0 → 2026.4.3

package/dist/src/a2a/streaming.d.ts

@@ -1,47 +1,237 @@
 /**
  * A2A streaming and async runtime primitives (T101).
  *
- * Provides an in-memory event bus for task status/artifact updates and
- * push-notification config storage helpers.
+ * @remarks
+ * Provides an in-memory event bus for task status/artifact updates,
+ * push-notification config storage helpers, webhook dispatch, and
+ * artifact delta assembly. All classes are designed for in-memory use
+ * and do not persist state across process restarts.
  */
 import type { Artifact, PushNotificationConfig, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from '@a2a-js/sdk';
+/**
+ * Union type of task stream events emitted by the event bus.
+ *
+ * @remarks
+ * Encompasses both status update and artifact update events from the A2A SDK.
+ */
 export type TaskStreamEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
 type StreamListener = (event: TaskStreamEvent) => void;
 /**
  * In-memory event bus for task lifecycle streaming events.
+ *
+ * @remarks
+ * Maintains per-task event history and per-task listener sets. Events are
+ * delivered synchronously to all registered listeners for the task. The
+ * history can be replayed via {@link TaskEventBus.getHistory} for catch-up
+ * semantics.
  */
 export declare class TaskEventBus {
+    /** Map of task ID to ordered event history */
     private history;
+    /** Map of task ID to active listener callbacks */
     private listeners;
+    /**
+     * Publish a task status update event.
+     *
+     * @remarks
+     * Convenience wrapper that delegates to {@link TaskEventBus.publish}.
+     *
+     * @param event - Status update event to publish
+     *
+     * @example
+     * ```typescript
+     * bus.publishStatusUpdate({ kind: 'status-update', taskId: 'task-1', status: { state: 'working', timestamp: new Date().toISOString() }, final: false });
+     * ```
+     */
     publishStatusUpdate(event: TaskStatusUpdateEvent): void;
+    /**
+     * Publish a task artifact update event.
+     *
+     * @remarks
+     * Convenience wrapper that delegates to {@link TaskEventBus.publish}.
+     *
+     * @param event - Artifact update event to publish
+     *
+     * @example
+     * ```typescript
+     * bus.publishArtifactUpdate({ kind: 'artifact-update', taskId: 'task-1', artifact: myArtifact });
+     * ```
+     */
     publishArtifactUpdate(event: TaskArtifactUpdateEvent): void;
+    /**
+     * Publish a task stream event to all listeners and history.
+     *
+     * @remarks
+     * Appends the event to the task's history, then synchronously delivers
+     * it to all registered listeners for that task.
+     *
+     * @param event - Task stream event to publish
+     *
+     * @example
+     * ```typescript
+     * bus.publish(statusUpdateEvent);
+     * ```
+     */
     publish(event: TaskStreamEvent): void;
+    /**
+     * Subscribe to events for a specific task.
+     *
+     * @remarks
+     * Returns an unsubscribe function that removes the listener. Automatically
+     * cleans up the listener set when the last listener is removed.
+     *
+     * @param taskId - ID of the task to subscribe to
+     * @param listener - Callback invoked for each event
+     * @returns Unsubscribe function that removes this listener
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = bus.subscribe('task-1', (event) => {
+     *   console.log('Event:', event);
+     * });
+     * // Later: unsubscribe();
+     * ```
+     */
     subscribe(taskId: string, listener: StreamListener): () => void;
+    /**
+     * Get the full event history for a task.
+     *
+     * @remarks
+     * Returns a shallow copy of the history array. Useful for catch-up
+     * replay when a new subscriber connects.
+     *
+     * @param taskId - ID of the task to retrieve history for
+     * @returns Array of past events for the task, or empty array if none
+     *
+     * @example
+     * ```typescript
+     * const events = bus.getHistory('task-1');
+     * ```
+     */
     getHistory(taskId: string): TaskStreamEvent[];
 }
+/** Options for the stream task events async iterator */
 export interface StreamIteratorOptions {
+    /**
+     * Timeout in milliseconds before the iterator yields control.
+     * @defaultValue undefined
+     */
     timeoutMs?: number;
 }
 /**
  * Build an async iterator for real-time task stream events.
+ *
+ * @remarks
+ * First replays the existing event history for catch-up, then yields
+ * new events as they arrive via the bus subscription. Uses a timeout
+ * (default 30s) to periodically yield control when no events arrive.
+ *
+ * @param bus - TaskEventBus to subscribe to
+ * @param taskId - ID of the task to stream events for
+ * @param options - Iterator options including timeout
+ * @returns Async generator yielding task stream events
+ *
+ * @example
+ * ```typescript
+ * for await (const event of streamTaskEvents(bus, 'task-1', { timeoutMs: 5000 })) {
+ *   console.log('Received:', event);
+ * }
+ * ```
  */
 export declare function streamTaskEvents(bus: TaskEventBus, taskId: string, options?: StreamIteratorOptions): AsyncGenerator<TaskStreamEvent>;
 /**
  * In-memory manager for async push-notification configs.
+ *
+ * @remarks
+ * Stores push-notification configurations keyed by task ID and config ID.
+ * Provides CRUD operations for registering, retrieving, listing, and
+ * removing webhook configurations.
  */
 export declare class PushNotificationConfigStore {
+    /** Nested map of task ID to config ID to push notification config */
     private configs;
+    /**
+     * Store a push-notification config for a task.
+     *
+     * @remarks
+     * Overwrites any existing config with the same task ID and config ID.
+     *
+     * @param taskId - ID of the task the config applies to
+     * @param configId - Unique identifier for this config within the task
+     * @param config - Push notification configuration to store
+     *
+     * @example
+     * ```typescript
+     * store.set('task-1', 'webhook-1', { url: 'https://example.com/hook', token: 'abc' });
+     * ```
+     */
     set(taskId: string, configId: string, config: PushNotificationConfig): void;
+    /**
+     * Retrieve a push-notification config by task and config ID.
+     *
+     * @param taskId - ID of the task
+     * @param configId - ID of the config to retrieve
+     * @returns The push notification config, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const config = store.get('task-1', 'webhook-1');
+     * ```
+     */
     get(taskId: string, configId: string): PushNotificationConfig | undefined;
+    /**
+     * List all push-notification configs for a task.
+     *
+     * @param taskId - ID of the task to list configs for
+     * @returns Array of push notification configs, or empty array if none
+     *
+     * @example
+     * ```typescript
+     * const configs = store.list('task-1');
+     * ```
+     */
     list(taskId: string): PushNotificationConfig[];
+    /**
+     * Delete a push-notification config.
+     *
+     * @remarks
+     * Removes the config and cleans up the task entry if no configs remain.
+     *
+     * @param taskId - ID of the task
+     * @param configId - ID of the config to delete
+     * @returns True if the config was found and removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const removed = store.delete('task-1', 'webhook-1');
+     * ```
+     */
     delete(taskId: string, configId: string): boolean;
 }
+/** Result of delivering a push notification to a single webhook */
 export interface PushNotificationDeliveryResult {
+    /** Identifier of the config that was dispatched to */
     configId: string;
+    /** Whether the delivery succeeded */
     ok: boolean;
+    /**
+     * HTTP status code from the webhook response.
+     * @defaultValue undefined
+     */
     status?: number;
+    /**
+     * Error message if delivery failed.
+     * @defaultValue undefined
+     */
     error?: string;
 }
+/**
+ * Transport function for sending HTTP requests to push-notification webhooks.
+ *
+ * @remarks
+ * Abstracts the HTTP transport layer to allow injection of custom fetch
+ * implementations or test doubles.
+ */
 export type PushTransport = (input: string, init?: {
     method?: string;
     headers?: Record<string, string>;
@@ -52,23 +242,105 @@ export type PushTransport = (input: string, init?: {
 }>;
 /**
  * Deliver task updates to registered push-notification webhooks.
+ *
+ * @remarks
+ * Dispatches events to all push-notification configs registered for a task
+ * via the configured transport. Builds authentication headers from the
+ * config's token and authentication fields. Falls back to global `fetch`
+ * if no transport is provided.
  */
 export declare class PushNotificationDispatcher {
     private readonly store;
     private readonly transport;
+    /**
+     * Create a PushNotificationDispatcher.
+     *
+     * @param store - Config store to look up webhook registrations
+     * @param transport - HTTP transport function for sending webhook requests
+     */
     constructor(store: PushNotificationConfigStore, transport?: PushTransport);
+    /**
+     * Dispatch a task event to all registered webhooks for the task.
+     *
+     * @remarks
+     * Sends the event payload as JSON to each registered push-notification
+     * URL in parallel. Captures delivery results including HTTP status and
+     * errors for each webhook.
+     *
+     * @param taskId - ID of the task whose webhooks to dispatch to
+     * @param event - Task stream event to deliver
+     * @returns Array of delivery results, one per registered config
+     *
+     * @example
+     * ```typescript
+     * const results = await dispatcher.dispatch('task-1', statusUpdateEvent);
+     * for (const r of results) {
+     *   if (!r.ok) console.error(`Failed to deliver to ${r.configId}: ${r.error}`);
+     * }
+     * ```
+     */
     dispatch(taskId: string, event: TaskStreamEvent): Promise<PushNotificationDeliveryResult[]>;
+    /** Build HTTP headers for push notification delivery including auth tokens. */
     private buildHeaders;
 }
 /**
  * Applies append/lastChunk artifact deltas into task-local snapshots.
+ *
+ * @remarks
+ * Maintains in-memory snapshots of artifacts per task. When an artifact
+ * update event with `append: true` arrives, parts are merged with the
+ * existing snapshot. The `lastChunk` flag is tracked in artifact metadata
+ * as `a2a:last_chunk`.
  */
 export declare class TaskArtifactAssembler {
+    /** Map of task ID to map of artifact ID to assembled artifact snapshot */
     private artifacts;
+    /**
+     * Apply an artifact update event to the assembled snapshot.
+     *
+     * @remarks
+     * If `append` is true and a prior snapshot exists, parts are concatenated.
+     * Otherwise the artifact is replaced. The `lastChunk` flag is always
+     * written to metadata.
+     *
+     * @param event - Artifact update event containing the delta
+     * @returns The merged artifact snapshot after applying the update
+     *
+     * @example
+     * ```typescript
+     * const assembler = new TaskArtifactAssembler();
+     * const merged = assembler.applyUpdate(artifactUpdateEvent);
+     * ```
+     */
     applyUpdate(event: TaskArtifactUpdateEvent): Artifact;
+    /**
+     * Get a specific assembled artifact by task and artifact ID.
+     *
+     * @param taskId - ID of the task
+     * @param artifactId - ID of the artifact to retrieve
+     * @returns The assembled artifact snapshot, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const artifact = assembler.get('task-1', 'art-1');
+     * ```
+     */
     get(taskId: string, artifactId: string): Artifact | undefined;
+    /**
+     * List all assembled artifacts for a task.
+     *
+     * @param taskId - ID of the task to list artifacts for
+     * @returns Array of assembled artifact snapshots, or empty array if none
+     *
+     * @example
+     * ```typescript
+     * const artifacts = assembler.list('task-1');
+     * ```
+     */
     list(taskId: string): Artifact[];
+    /** Merge a new artifact update event into an existing artifact snapshot, handling append semantics. */
     private mergeArtifact;
+    /** Inject the `a2a:last_chunk` marker into artifact metadata. */
     private withLastChunk;
 }
 export {};

package/dist/src/a2a/streaming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../../src/a2a/streaming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GAAG,qBAAqB,GAAG,uBAAuB,CAAC;AAE9E,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAevD;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,SAAS,CAA0C;IAE3D,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI;IAIvD,qBAAqB,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI;IAI3D,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAcrC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI;IAkB/D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;CAG9C;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAuB,gBAAgB,CACrC,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAAC,eAAe,CAAC,CA8CjC;AAED;;GAEG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,OAAO,CAA0D;IAEzE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAS3E,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IAIzE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,EAAE;IAI9C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;CAYlD;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,KACE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE9C;;GAEG;AACH,qBAAa,0BAA0B;IAEnC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,2BAA2B,EAClC,SAAS,GAAE,aAK3B;IAGG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,8BAA8B,EAAE,CAAC;IAiD5C,OAAO,CAAC,YAAY;CAoBrB;AAED;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,SAAS,CAA4C;IAE7D,WAAW,CAAC,KAAK,EAAE,uBAAuB,GAAG,QAAQ;IAoBrD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI7D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIhC,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,aAAa;CAStB"}
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../../src/a2a/streaming.ts"],"names":[],"mappings":"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"}