@cleocode/lafs-protocol 1.2.2 → 1.3.1

package/dist/src/a2a/index.js

@@ -1,36 +1,70 @@
 /**
- * LAFS Agent-to-Agent (A2A) Integration
+ * LAFS Agent-to-Agent (A2A) Integration v2.0
  *
- * This module provides integration between LAFS and the official
- * @a2a-js/sdk for Agent-to-Agent communication.
+ * 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-protocol/a2a';
+ * import {
+ *   createLafsArtifact,
+ *   createTextArtifact,
+ *   LafsA2AResult,
+ *   isExtensionRequired
+ * } from '@cleocode/lafs-protocol/a2a';
+ *
+ * // Use A2A SDK directly for client operations
  * import { ClientFactory } from '@a2a-js/sdk/client';
- * import { withLafsEnvelope } from '@cleocode/lafs-protocol/a2a';
  *
- * // Create official A2A client
  * const factory = new ClientFactory();
- * const a2aClient = await factory.createFromUrl('http://agent.example.com');
- *
- * // Wrap with LAFS support
- * const client = withLafsEnvelope(a2aClient, {
- *   defaultBudget: { maxTokens: 4000 }
- * });
- *
- * // Send message
- * const result = await client.sendMessage({
- *   message: {
- *     role: 'user',
- *     parts: [{ text: 'Analyze data' }]
- *   }
- * });
+ * const client = await factory.createFromUrl('https://agent.example.com');
+ * const result = await client.sendMessage({...});
  *
- * // Extract LAFS envelope from response
- * const envelope = result.getLafsEnvelope();
- * if (envelope) {
- *   console.log(envelope._meta._tokenEstimate);
- * }
+ * // Wrap result with LAFS helpers
+ * const lafsResult = new LafsA2AResult(result, {}, 'req-001');
+ * const envelope = lafsResult.getLafsEnvelope();
  * ```
  */
-export { withLafsEnvelope, LafsA2AClient, LafsA2AResult, createLafsArtifact } from './bridge.js';
+// ============================================================================
+// Core Exports
+// ============================================================================
+export { 
+// Result wrapper
+LafsA2AResult, 
+// Artifact helpers
+createLafsArtifact, createTextArtifact, createFileArtifact, 
+// Extension helpers
+isExtensionRequired, getExtensionParams, } 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, 
+// Task manager
+TaskManager, 
+// LAFS integration
+attachLafsEnvelope, } from './task-lifecycle.js';
+// ============================================================================
+// Protocol Bindings (T100)
+// ============================================================================
+export * from './bindings/index.js';

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

@@ -0,0 +1,98 @@
+/**
+ * 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);
+}
+/** Options for creating a new task */
+export interface CreateTaskOptions {
+    contextId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** 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;
+    /** 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;
+}
+/**
+ * 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;

package/dist/src/a2a/task-lifecycle.js

@@ -0,0 +1,263 @@
+/**
+ * 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 { createLafsArtifact } from './bridge.js';
+// ============================================================================
+// State Constants
+// ============================================================================
+/** States from which no further transitions are possible */
+export const TERMINAL_STATES = new Set([
+    'completed',
+    'failed',
+    'canceled',
+    'rejected',
+]);
+/** States where the task is paused awaiting external input */
+export const INTERRUPTED_STATES = new Set([
+    'input-required',
+    'auth-required',
+]);
+/** Valid state transitions (adjacency map). Terminal states have empty outgoing sets. */
+export const VALID_TRANSITIONS = new Map([
+    ['submitted', new Set(['working', 'canceled', 'rejected', 'failed'])],
+    ['working', new Set(['completed', 'failed', 'canceled', 'input-required', 'auth-required'])],
+    ['input-required', new Set(['working', 'canceled', 'failed'])],
+    ['auth-required', new Set(['working', 'canceled', 'failed'])],
+    ['completed', new Set()],
+    ['failed', new Set()],
+    ['canceled', new Set()],
+    ['rejected', new Set()],
+    ['unknown', new Set(['submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required'])],
+]);
+// ============================================================================
+// State Functions
+// ============================================================================
+/** Check if a transition from one state to another is valid */
+export function isValidTransition(from, to) {
+    const allowed = VALID_TRANSITIONS.get(from);
+    return allowed ? allowed.has(to) : false;
+}
+/** Check if a state is terminal (no further transitions allowed) */
+export function isTerminalState(state) {
+    return TERMINAL_STATES.has(state);
+}
+/** Check if a state is interrupted (paused awaiting input) */
+export function isInterruptedState(state) {
+    return INTERRUPTED_STATES.has(state);
+}
+// ============================================================================
+// Error Classes
+// ============================================================================
+/** Thrown when attempting an invalid state transition */
+export class InvalidStateTransitionError extends Error {
+    taskId;
+    fromState;
+    toState;
+    constructor(taskId, fromState, toState) {
+        super(`Invalid transition for task ${taskId}: ${fromState} -> ${toState}`);
+        this.name = 'InvalidStateTransitionError';
+        this.taskId = taskId;
+        this.fromState = fromState;
+        this.toState = toState;
+    }
+}
+/** Thrown when attempting to modify a task in a terminal state */
+export class TaskImmutabilityError extends Error {
+    taskId;
+    terminalState;
+    constructor(taskId, terminalState) {
+        super(`Task ${taskId} is in terminal state ${terminalState} and cannot be modified`);
+        this.name = 'TaskImmutabilityError';
+        this.taskId = taskId;
+        this.terminalState = terminalState;
+    }
+}
+/** Thrown when a task is not found */
+export class TaskNotFoundError extends Error {
+    taskId;
+    constructor(taskId) {
+        super(`Task not found: ${taskId}`);
+        this.name = 'TaskNotFoundError';
+        this.taskId = taskId;
+    }
+}
+// ============================================================================
+// ID Generation
+// ============================================================================
+function generateId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * In-memory task manager implementing A2A task lifecycle.
+ * Enforces valid state transitions and terminal state immutability.
+ */
+export class TaskManager {
+    tasks = new Map();
+    contextIndex = new Map();
+    /** Create a new task in the submitted state */
+    createTask(options) {
+        const id = generateId();
+        const contextId = options?.contextId ?? generateId();
+        const task = {
+            id,
+            contextId,
+            kind: 'task',
+            status: {
+                state: 'submitted',
+                timestamp: new Date().toISOString(),
+            },
+            ...(options?.metadata && { metadata: options.metadata }),
+        };
+        this.tasks.set(id, task);
+        // Index by contextId
+        let contextTasks = this.contextIndex.get(contextId);
+        if (!contextTasks) {
+            contextTasks = new Set();
+            this.contextIndex.set(contextId, contextTasks);
+        }
+        contextTasks.add(id);
+        return structuredClone(task);
+    }
+    /** Get a task by ID. Throws TaskNotFoundError if not found. */
+    getTask(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        return structuredClone(task);
+    }
+    /** List tasks with optional filtering and pagination */
+    listTasks(options) {
+        let taskIds;
+        if (options?.contextId) {
+            const contextTasks = this.contextIndex.get(options.contextId);
+            taskIds = contextTasks ? [...contextTasks] : [];
+        }
+        else {
+            taskIds = [...this.tasks.keys()];
+        }
+        // Filter by state
+        if (options?.state) {
+            taskIds = taskIds.filter(id => {
+                const task = this.tasks.get(id);
+                return task && task.status.state === options.state;
+            });
+        }
+        // Sort for deterministic pagination
+        taskIds.sort();
+        // Apply page token (cursor-based: token is the last seen task ID)
+        if (options?.pageToken) {
+            const startIdx = taskIds.indexOf(options.pageToken);
+            if (startIdx >= 0) {
+                taskIds = taskIds.slice(startIdx + 1);
+            }
+        }
+        // Apply limit
+        const limit = options?.limit ?? taskIds.length;
+        const pageTaskIds = taskIds.slice(0, limit);
+        const hasMore = taskIds.length > limit;
+        const tasks = pageTaskIds.map(id => structuredClone(this.tasks.get(id)));
+        const nextPageToken = hasMore ? pageTaskIds[pageTaskIds.length - 1] : undefined;
+        return { tasks, nextPageToken };
+    }
+    /**
+     * 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, state, message) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        const currentState = task.status.state;
+        if (isTerminalState(currentState)) {
+            throw new TaskImmutabilityError(taskId, currentState);
+        }
+        if (!isValidTransition(currentState, state)) {
+            throw new InvalidStateTransitionError(taskId, currentState, state);
+        }
+        const status = {
+            state,
+            timestamp: new Date().toISOString(),
+            ...(message && { message }),
+        };
+        task.status = status;
+        return structuredClone(task);
+    }
+    /**
+     * Add an artifact to a task.
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    addArtifact(taskId, artifact) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        if (isTerminalState(task.status.state)) {
+            throw new TaskImmutabilityError(taskId, task.status.state);
+        }
+        if (!task.artifacts) {
+            task.artifacts = [];
+        }
+        task.artifacts.push(artifact);
+        return structuredClone(task);
+    }
+    /**
+     * Add a message to task history.
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    addHistory(taskId, message) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        if (isTerminalState(task.status.state)) {
+            throw new TaskImmutabilityError(taskId, task.status.state);
+        }
+        if (!task.history) {
+            task.history = [];
+        }
+        task.history.push(message);
+        return structuredClone(task);
+    }
+    /** Cancel a task by transitioning to canceled state */
+    cancelTask(taskId) {
+        return this.updateTaskStatus(taskId, 'canceled');
+    }
+    /** Get all tasks in a given context */
+    getTasksByContext(contextId) {
+        const taskIds = this.contextIndex.get(contextId);
+        if (!taskIds)
+            return [];
+        return [...taskIds].map(id => structuredClone(this.tasks.get(id)));
+    }
+    /** Check if a task is in a terminal state */
+    isTerminal(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        return isTerminalState(task.status.state);
+    }
+}
+// ============================================================================
+// LAFS Integration
+// ============================================================================
+/**
+ * Attach a LAFS envelope as an artifact to an A2A task.
+ * Uses createLafsArtifact() from bridge.ts to wrap the envelope.
+ */
+export function attachLafsEnvelope(manager, taskId, envelope) {
+    const artifact = createLafsArtifact(envelope);
+    return manager.addArtifact(taskId, artifact);
+}