@cleocode/lafs 1.8.0

package/dist/src/a2a/index.js

@@ -0,0 +1,76 @@
+/**
+ * LAFS Agent-to-Agent (A2A) Integration v2.0
+ *
+ * Full integration with the official @a2a-js/sdk for Agent-to-Agent communication.
+ * Implements A2A Protocol v1.0+ specification.
+ *
+ * Reference: specs/external/specification.md
+ *
+ * @example
+ * ```typescript
+ * import type { AgentCard, Task } from '@cleocode/lafs/a2a';
+ * import {
+ *   createLafsArtifact,
+ *   createTextArtifact,
+ *   LafsA2AResult,
+ *   isExtensionRequired
+ * } from '@cleocode/lafs/a2a';
+ *
+ * // Use A2A SDK directly for client operations
+ * import { ClientFactory } from '@a2a-js/sdk/client';
+ *
+ * const factory = new ClientFactory();
+ * const client = await factory.createFromUrl('https://agent.example.com');
+ * const result = await client.sendMessage({...});
+ *
+ * // Wrap result with LAFS helpers
+ * const lafsResult = new LafsA2AResult(result, {}, 'req-001');
+ * const envelope = lafsResult.getLafsEnvelope();
+ * ```
+ */
+// ============================================================================
+// Core Exports
+// ============================================================================
+export { 
+// Result wrapper
+LafsA2AResult, 
+// Artifact helpers
+createLafsArtifact, createTextArtifact, createFileArtifact, 
+// Extension helpers
+isExtensionRequired, getExtensionParams, 
+// Constants
+AGENT_CARD_PATH, HTTP_EXTENSION_HEADER, } from './bridge.js';
+// ============================================================================
+// Extensions (T098)
+// ============================================================================
+export { 
+// Constants
+LAFS_EXTENSION_URI, A2A_EXTENSIONS_HEADER, 
+// Functions
+parseExtensionsHeader, negotiateExtensions, formatExtensionsHeader, buildLafsExtension, 
+// Error class
+ExtensionSupportRequiredError, 
+// Middleware
+extensionNegotiationMiddleware, } from './extensions.js';
+// ============================================================================
+// Task Lifecycle (T099)
+// ============================================================================
+export { 
+// State constants
+TERMINAL_STATES, INTERRUPTED_STATES, VALID_TRANSITIONS, 
+// State functions
+isValidTransition, isTerminalState, isInterruptedState, 
+// Error classes
+InvalidStateTransitionError, TaskImmutabilityError, TaskNotFoundError, TaskRefinementError, 
+// Task manager
+TaskManager, 
+// LAFS integration
+attachLafsEnvelope, } from './task-lifecycle.js';
+// ============================================================================
+// Streaming and Async (T101)
+// ============================================================================
+export { TaskEventBus, PushNotificationConfigStore, PushNotificationDispatcher, TaskArtifactAssembler, streamTaskEvents, } from './streaming.js';
+// ============================================================================
+// Protocol Bindings (T100)
+// ============================================================================
+export * from './bindings/index.js';

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

@@ -0,0 +1,74 @@
+/**
+ * A2A streaming and async runtime primitives (T101).
+ *
+ * Provides an in-memory event bus for task status/artifact updates and
+ * push-notification config storage helpers.
+ */
+import type { Artifact, PushNotificationConfig, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from "@a2a-js/sdk";
+export type TaskStreamEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+type StreamListener = (event: TaskStreamEvent) => void;
+/**
+ * In-memory event bus for task lifecycle streaming events.
+ */
+export declare class TaskEventBus {
+    private history;
+    private listeners;
+    publishStatusUpdate(event: TaskStatusUpdateEvent): void;
+    publishArtifactUpdate(event: TaskArtifactUpdateEvent): void;
+    publish(event: TaskStreamEvent): void;
+    subscribe(taskId: string, listener: StreamListener): () => void;
+    getHistory(taskId: string): TaskStreamEvent[];
+}
+export interface StreamIteratorOptions {
+    timeoutMs?: number;
+}
+/**
+ * Build an async iterator for real-time task stream events.
+ */
+export declare function streamTaskEvents(bus: TaskEventBus, taskId: string, options?: StreamIteratorOptions): AsyncGenerator<TaskStreamEvent>;
+/**
+ * In-memory manager for async push-notification configs.
+ */
+export declare class PushNotificationConfigStore {
+    private configs;
+    set(taskId: string, configId: string, config: PushNotificationConfig): void;
+    get(taskId: string, configId: string): PushNotificationConfig | undefined;
+    list(taskId: string): PushNotificationConfig[];
+    delete(taskId: string, configId: string): boolean;
+}
+export interface PushNotificationDeliveryResult {
+    configId: string;
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
+export type PushTransport = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+/**
+ * Deliver task updates to registered push-notification webhooks.
+ */
+export declare class PushNotificationDispatcher {
+    private readonly store;
+    private readonly transport;
+    constructor(store: PushNotificationConfigStore, transport?: PushTransport);
+    dispatch(taskId: string, event: TaskStreamEvent): Promise<PushNotificationDeliveryResult[]>;
+    private buildHeaders;
+}
+/**
+ * Applies append/lastChunk artifact deltas into task-local snapshots.
+ */
+export declare class TaskArtifactAssembler {
+    private artifacts;
+    applyUpdate(event: TaskArtifactUpdateEvent): Artifact;
+    get(taskId: string, artifactId: string): Artifact | undefined;
+    list(taskId: string): Artifact[];
+    private mergeArtifact;
+    private withLastChunk;
+}
+export {};

package/dist/src/a2a/streaming.js

@@ -0,0 +1,265 @@
+/**
+ * A2A streaming and async runtime primitives (T101).
+ *
+ * Provides an in-memory event bus for task status/artifact updates and
+ * push-notification config storage helpers.
+ */
+function resolveTaskId(event) {
+    const candidate = event;
+    const taskId = candidate.taskId ?? candidate.task?.id;
+    if (!taskId) {
+        throw new Error("Task stream event is missing task identifier");
+    }
+    return taskId;
+}
+/**
+ * In-memory event bus for task lifecycle streaming events.
+ */
+export class TaskEventBus {
+    history = new Map();
+    listeners = new Map();
+    publishStatusUpdate(event) {
+        this.publish(event);
+    }
+    publishArtifactUpdate(event) {
+        this.publish(event);
+    }
+    publish(event) {
+        const taskId = resolveTaskId(event);
+        const events = this.history.get(taskId) ?? [];
+        events.push(event);
+        this.history.set(taskId, events);
+        const listeners = this.listeners.get(taskId);
+        if (listeners) {
+            for (const listener of listeners) {
+                listener(event);
+            }
+        }
+    }
+    subscribe(taskId, listener) {
+        let set = this.listeners.get(taskId);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(taskId, set);
+        }
+        set.add(listener);
+        return () => {
+            const active = this.listeners.get(taskId);
+            if (!active)
+                return;
+            active.delete(listener);
+            if (active.size === 0) {
+                this.listeners.delete(taskId);
+            }
+        };
+    }
+    getHistory(taskId) {
+        return [...(this.history.get(taskId) ?? [])];
+    }
+}
+/**
+ * Build an async iterator for real-time task stream events.
+ */
+export async function* streamTaskEvents(bus, taskId, options = {}) {
+    const queue = [];
+    let wakeUp = null;
+    const unsubscribe = bus.subscribe(taskId, (event) => {
+        queue.push(event);
+        if (wakeUp) {
+            wakeUp();
+            wakeUp = null;
+        }
+    });
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    try {
+        // Emit existing history first for catch-up behavior.
+        for (const event of bus.getHistory(taskId)) {
+            yield event;
+        }
+        while (true) {
+            if (queue.length > 0) {
+                const event = queue.shift();
+                if (event) {
+                    yield event;
+                    continue;
+                }
+            }
+            await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    if (wakeUp === resolve) {
+                        wakeUp = null;
+                    }
+                    resolve();
+                }, timeoutMs);
+                wakeUp = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+        }
+    }
+    finally {
+        unsubscribe();
+    }
+}
+/**
+ * In-memory manager for async push-notification configs.
+ */
+export class PushNotificationConfigStore {
+    configs = new Map();
+    set(taskId, configId, config) {
+        let taskConfigs = this.configs.get(taskId);
+        if (!taskConfigs) {
+            taskConfigs = new Map();
+            this.configs.set(taskId, taskConfigs);
+        }
+        taskConfigs.set(configId, config);
+    }
+    get(taskId, configId) {
+        return this.configs.get(taskId)?.get(configId);
+    }
+    list(taskId) {
+        return [...(this.configs.get(taskId)?.values() ?? [])];
+    }
+    delete(taskId, configId) {
+        const taskConfigs = this.configs.get(taskId);
+        if (!taskConfigs) {
+            return false;
+        }
+        const removed = taskConfigs.delete(configId);
+        if (taskConfigs.size === 0) {
+            this.configs.delete(taskId);
+        }
+        return removed;
+    }
+}
+/**
+ * Deliver task updates to registered push-notification webhooks.
+ */
+export class PushNotificationDispatcher {
+    store;
+    transport;
+    constructor(store, transport = async (input, init) => {
+        if (typeof fetch !== "function") {
+            throw new Error("Global fetch is not available for push dispatch");
+        }
+        return fetch(input, init);
+    }) {
+        this.store = store;
+        this.transport = transport;
+    }
+    async dispatch(taskId, event) {
+        const configs = this.store.list(taskId);
+        if (configs.length === 0) {
+            return [];
+        }
+        const payload = {
+            taskId,
+            event,
+            timestamp: new Date().toISOString(),
+        };
+        const deliveries = configs.map(async (config, index) => {
+            const configId = config.id ?? `${taskId}:${index}`;
+            if (!config.url) {
+                return {
+                    configId,
+                    ok: false,
+                    error: "Push notification config is missing url",
+                };
+            }
+            const headers = this.buildHeaders(config);
+            try {
+                const response = await this.transport(config.url, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                return {
+                    configId,
+                    ok: response.ok,
+                    status: response.status,
+                    ...(response.ok ? {} : { error: `HTTP ${response.status}` }),
+                };
+            }
+            catch (error) {
+                return {
+                    configId,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        });
+        return Promise.all(deliveries);
+    }
+    buildHeaders(config) {
+        const headers = {
+            "content-type": "application/json",
+        };
+        if (config.token) {
+            headers["x-a2a-task-token"] = config.token;
+        }
+        const scheme = config.authentication?.schemes?.[0];
+        const credentials = config.authentication?.credentials;
+        if (scheme && credentials) {
+            headers.authorization = `${scheme} ${credentials}`;
+        }
+        else if (config.token) {
+            headers.authorization = `Bearer ${config.token}`;
+        }
+        return headers;
+    }
+}
+/**
+ * Applies append/lastChunk artifact deltas into task-local snapshots.
+ */
+export class TaskArtifactAssembler {
+    artifacts = new Map();
+    applyUpdate(event) {
+        if (!event.artifact?.artifactId) {
+            throw new Error("Task artifact update is missing artifactId");
+        }
+        const taskId = resolveTaskId(event);
+        const artifactId = event.artifact.artifactId;
+        let taskArtifacts = this.artifacts.get(taskId);
+        if (!taskArtifacts) {
+            taskArtifacts = new Map();
+            this.artifacts.set(taskId, taskArtifacts);
+        }
+        const prior = taskArtifacts.get(artifactId);
+        const merged = this.mergeArtifact(prior, event);
+        taskArtifacts.set(artifactId, merged);
+        return merged;
+    }
+    get(taskId, artifactId) {
+        return this.artifacts.get(taskId)?.get(artifactId);
+    }
+    list(taskId) {
+        return [...(this.artifacts.get(taskId)?.values() ?? [])];
+    }
+    mergeArtifact(prior, event) {
+        const next = event.artifact;
+        const append = Boolean(event.append);
+        const lastChunk = Boolean(event.lastChunk);
+        if (!append || !prior) {
+            return {
+                ...next,
+                metadata: this.withLastChunk(next.metadata, lastChunk),
+            };
+        }
+        return {
+            ...prior,
+            ...next,
+            parts: [...(prior.parts ?? []), ...(next.parts ?? [])],
+            metadata: this.withLastChunk({
+                ...(prior.metadata ?? {}),
+                ...(next.metadata ?? {}),
+            }, lastChunk),
+        };
+    }
+    withLastChunk(metadata, lastChunk) {
+        return {
+            ...(metadata ?? {}),
+            "a2a:last_chunk": lastChunk,
+        };
+    }
+}

package/dist/src/a2a/task-lifecycle.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A2A Task Lifecycle Management
+ *
+ * State machine enforcement, task CRUD, and LAFS integration
+ * for A2A Protocol v1.0+ compliance.
+ *
+ * Reference: A2A spec Section 6 (Task Lifecycle)
+ */
+import type { Task, TaskState, Artifact, Message } from '@a2a-js/sdk';
+import type { LAFSEnvelope } from '../types.js';
+/** States from which no further transitions are possible */
+export declare const TERMINAL_STATES: ReadonlySet<TaskState>;
+/** States where the task is paused awaiting external input */
+export declare const INTERRUPTED_STATES: ReadonlySet<TaskState>;
+/** Valid state transitions (adjacency map). Terminal states have empty outgoing sets. */
+export declare const VALID_TRANSITIONS: ReadonlyMap<TaskState, ReadonlySet<TaskState>>;
+/** Check if a transition from one state to another is valid */
+export declare function isValidTransition(from: TaskState, to: TaskState): boolean;
+/** Check if a state is terminal (no further transitions allowed) */
+export declare function isTerminalState(state: TaskState): boolean;
+/** Check if a state is interrupted (paused awaiting input) */
+export declare function isInterruptedState(state: TaskState): boolean;
+/** Thrown when attempting an invalid state transition */
+export declare class InvalidStateTransitionError extends Error {
+    readonly taskId: string;
+    readonly fromState: TaskState;
+    readonly toState: TaskState;
+    constructor(taskId: string, fromState: TaskState, toState: TaskState);
+}
+/** Thrown when attempting to modify a task in a terminal state */
+export declare class TaskImmutabilityError extends Error {
+    readonly taskId: string;
+    readonly terminalState: TaskState;
+    constructor(taskId: string, terminalState: TaskState);
+}
+/** Thrown when a task is not found */
+export declare class TaskNotFoundError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/** Thrown when a refinement/follow-up task references invalid parent tasks */
+export declare class TaskRefinementError extends Error {
+    readonly referenceTaskIds: string[];
+    constructor(message: string, referenceTaskIds: string[]);
+}
+/** Options for creating a new task */
+export interface CreateTaskOptions {
+    contextId?: string;
+    metadata?: Record<string, unknown>;
+    referenceTaskIds?: string[];
+    parallelFollowUp?: boolean;
+}
+/** Options for listing tasks */
+export interface ListTasksOptions {
+    contextId?: string;
+    state?: TaskState;
+    limit?: number;
+    pageToken?: string;
+}
+/** Paginated result from listTasks */
+export interface ListTasksResult {
+    tasks: Task[];
+    nextPageToken?: string;
+}
+/**
+ * In-memory task manager implementing A2A task lifecycle.
+ * Enforces valid state transitions and terminal state immutability.
+ */
+export declare class TaskManager {
+    private tasks;
+    private contextIndex;
+    /** Create a new task in the submitted state */
+    createTask(options?: CreateTaskOptions): Task;
+    /** Create a refinement/follow-up task referencing existing task(s). */
+    createRefinedTask(referenceTaskIds: string[], options?: Omit<CreateTaskOptions, 'referenceTaskIds'>): Task;
+    /** Get a task by ID. Throws TaskNotFoundError if not found. */
+    getTask(taskId: string): Task;
+    /** List tasks with optional filtering and pagination */
+    listTasks(options?: ListTasksOptions): ListTasksResult;
+    /**
+     * Update task status. Enforces valid transitions and terminal state immutability.
+     * @throws InvalidStateTransitionError if the transition is not valid
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    updateTaskStatus(taskId: string, state: TaskState, message?: Message): Task;
+    /**
+     * Add an artifact to a task.
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    addArtifact(taskId: string, artifact: Artifact): Task;
+    /**
+     * Add a message to task history.
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    addHistory(taskId: string, message: Message): Task;
+    /** Cancel a task by transitioning to canceled state */
+    cancelTask(taskId: string): Task;
+    /** Get all tasks in a given context */
+    getTasksByContext(contextId: string): Task[];
+    /** Check if a task is in a terminal state */
+    isTerminal(taskId: string): boolean;
+    private resolveContextForReferenceTasks;
+    private validateReferenceTasks;
+}
+/**
+ * Attach a LAFS envelope as an artifact to an A2A task.
+ * Uses createLafsArtifact() from bridge.ts to wrap the envelope.
+ */
+export declare function attachLafsEnvelope(manager: TaskManager, taskId: string, envelope: LAFSEnvelope): Task;