agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/tasks/task-manager.d.ts

@@ -0,0 +1,306 @@
+/**
+ * A2A Task Manager
+ *
+ * Manages the A2A task lifecycle with a complete state machine implementation.
+ * Provides task creation, state transitions, artifact management, and history tracking.
+ *
+ * @module adapters/a2a/tasks/task-manager
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+import { EventEmitter } from 'events';
+import type { A2AMessage, TaskStatus, A2AArtifact } from '../jsonrpc/methods.js';
+import { TaskStore, type A2ATask, type TaskHistoryEntry, type TaskError, type TaskStoreConfig } from './task-store.js';
+/**
+ * Valid state transitions for the A2A task state machine.
+ *
+ * State Machine Diagram:
+ * ```
+ *                     +-------------+
+ *                     |  submitted  |
+ *                     +------+------+
+ *                            |
+ *               +------------+------------+
+ *               v            v            v
+ *         +----------+ +----------+ +----------+
+ *         | rejected | | working  | | canceled |
+ *         +----------+ +----+-----+ +----------+
+ *                           |
+ *            +--------------+-------------+
+ *            v              v             v
+ *     +-------------+ +----------+ +----------+
+ *     |input_required| | completed| |  failed  |
+ *     +------+------+ +----------+ +----------+
+ *            |
+ *            v
+ *     +-------------+
+ *     |auth_required|
+ *     +-------------+
+ * ```
+ */
+export declare const VALID_TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>>;
+/**
+ * Terminal states where no further transitions are allowed
+ */
+export declare const TERMINAL_STATES: readonly TaskStatus[];
+/**
+ * Check if a status is terminal (no further transitions possible)
+ */
+export declare function isTerminal(status: TaskStatus): boolean;
+/**
+ * Check if a state transition is valid
+ */
+export declare function isValidTransition(from: TaskStatus, to: TaskStatus): boolean;
+/**
+ * Task manager configuration
+ */
+export interface TaskManagerConfig {
+    /** Task store configuration */
+    readonly storeConfig?: TaskStoreConfig;
+    /** Default agent ID for tasks without explicit agent */
+    readonly defaultAgentId?: string;
+    /** Whether to generate context IDs for tasks without one */
+    readonly autoGenerateContextId?: boolean;
+    /** ID generator function */
+    readonly idGenerator?: () => string;
+    /** Context ID generator function */
+    readonly contextIdGenerator?: () => string;
+    /** Timestamp generator function */
+    readonly timestampGenerator?: () => Date;
+}
+/**
+ * Default task manager configuration
+ */
+export declare const DEFAULT_TASK_MANAGER_CONFIG: Required<TaskManagerConfig>;
+/**
+ * Options for creating a new task
+ */
+export interface CreateTaskOptions {
+    /** Explicit task ID (auto-generated if not provided) */
+    readonly id?: string;
+    /** Context ID for multi-turn conversations */
+    readonly contextId?: string;
+    /** Agent ID to handle this task */
+    readonly agentId?: string;
+    /** Parent task ID for subtasks */
+    readonly parentTaskId?: string;
+    /** Task priority */
+    readonly priority?: number;
+    /** Custom tags */
+    readonly tags?: string[];
+    /** Custom metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Task state change event
+ */
+export interface TaskStateChangeEvent {
+    /** Task ID */
+    readonly taskId: string;
+    /** Task instance */
+    readonly task: A2ATask;
+    /** Previous status */
+    readonly previousStatus: TaskStatus;
+    /** New status */
+    readonly newStatus: TaskStatus;
+    /** Transition timestamp */
+    readonly timestamp: Date;
+    /** Optional reason for transition */
+    readonly reason?: string;
+}
+/**
+ * Task artifact event
+ */
+export interface TaskArtifactEvent {
+    /** Task ID */
+    readonly taskId: string;
+    /** Artifact */
+    readonly artifact: A2AArtifact;
+    /** Whether this is an update to an existing artifact */
+    readonly isUpdate: boolean;
+    /** Timestamp */
+    readonly timestamp: Date;
+}
+/**
+ * Task error event
+ */
+export interface TaskErrorEvent {
+    /** Task ID */
+    readonly taskId: string;
+    /** Error details */
+    readonly error: TaskError;
+    /** Timestamp */
+    readonly timestamp: Date;
+}
+/**
+ * A2A Task Manager
+ *
+ * Manages the complete lifecycle of A2A tasks including:
+ * - Task creation from messages
+ * - State machine transitions with validation
+ * - Artifact management
+ * - History tracking
+ * - Event emission for SSE streaming
+ */
+export declare class TaskManager extends EventEmitter {
+    private readonly config;
+    private readonly store;
+    constructor(config?: TaskManagerConfig);
+    /**
+     * Create a new task from an A2A message
+     */
+    createTask(message: A2AMessage, options?: CreateTaskOptions): A2ATask;
+    /**
+     * Create a subtask under a parent task
+     */
+    createSubtask(parentTaskId: string, message: A2AMessage, options?: Omit<CreateTaskOptions, 'parentTaskId'>): A2ATask | null;
+    /**
+     * Get a task by ID
+     */
+    getTask(taskId: string): A2ATask | null;
+    /**
+     * Check if a task exists
+     */
+    hasTask(taskId: string): boolean;
+    /**
+     * Get tasks by context ID
+     */
+    getTasksByContext(contextId: string): A2ATask[];
+    /**
+     * Get tasks by status
+     */
+    getTasksByStatus(status: TaskStatus): A2ATask[];
+    /**
+     * Get tasks by agent ID
+     */
+    getTasksByAgent(agentId: string): A2ATask[];
+    /**
+     * Get subtasks of a parent task
+     */
+    getSubtasks(parentTaskId: string): A2ATask[];
+    /**
+     * Transition a task to a new status
+     *
+     * @throws Error if the transition is invalid
+     */
+    transition(taskId: string, newStatus: TaskStatus, reason?: string, triggeredBy?: string): A2ATask;
+    /**
+     * Start working on a task (submitted -> working)
+     */
+    startTask(taskId: string, reason?: string): A2ATask;
+    /**
+     * Complete a task (working -> completed)
+     */
+    completeTask(taskId: string, artifacts?: A2AArtifact[], reason?: string): A2ATask;
+    /**
+     * Fail a task (working -> failed)
+     */
+    failTask(taskId: string, error: TaskError, reason?: string): A2ATask;
+    /**
+     * Cancel a task
+     */
+    cancelTask(taskId: string, reason?: string): A2ATask;
+    /**
+     * Reject a task (submitted -> rejected)
+     */
+    rejectTask(taskId: string, reason: string): A2ATask;
+    /**
+     * Request input from user (working -> input_required)
+     */
+    requestInput(taskId: string, prompt?: string): A2ATask;
+    /**
+     * Request authentication (working/input_required -> auth_required)
+     */
+    requestAuth(taskId: string, authType?: string): A2ATask;
+    /**
+     * Resume task after input or auth (input_required/auth_required -> working)
+     */
+    resumeTask(taskId: string, reason?: string): A2ATask;
+    /**
+     * Provide input to a task and resume
+     */
+    provideInput(taskId: string, input: A2AMessage): A2ATask;
+    /**
+     * Add an artifact to a task
+     */
+    addArtifact(taskId: string, artifact: A2AArtifact): A2ATask;
+    /**
+     * Add multiple artifacts to a task
+     */
+    addArtifacts(taskId: string, artifacts: A2AArtifact[]): A2ATask;
+    /**
+     * Create an artifact from a message
+     */
+    createArtifactFromMessage(message: A2AMessage, name?: string, description?: string): A2AArtifact;
+    /**
+     * Create a text artifact
+     */
+    createTextArtifact(id: string, name: string, text: string, metadata?: Record<string, unknown>): A2AArtifact;
+    /**
+     * Create a data artifact
+     */
+    createDataArtifact(id: string, name: string, data: Record<string, unknown>, metadata?: Record<string, unknown>): A2AArtifact;
+    /**
+     * Create a file artifact
+     */
+    createFileArtifact(id: string, name: string, file: {
+        name: string;
+        mimeType: string;
+        bytes?: string;
+        uri?: string;
+    }, metadata?: Record<string, unknown>): A2AArtifact;
+    /**
+     * Get task history
+     */
+    getTaskHistory(taskId: string): TaskHistoryEntry[] | null;
+    /**
+     * Get the duration a task has been in its current status
+     */
+    getStatusDuration(taskId: string): number | null;
+    /**
+     * Get the total duration of a task (from creation to now or completion)
+     */
+    getTotalDuration(taskId: string): number | null;
+    /**
+     * Query tasks with filtering and pagination
+     */
+    queryTasks(options?: Parameters<TaskStore['query']>[0]): import("./task-store.js").TaskQueryResult;
+    /**
+     * Get store statistics
+     */
+    getStats(): {
+        totalTasks: number;
+        tasksByStatus: Record<TaskStatus, number>;
+        contextCount: number;
+        agentCount: number;
+    };
+    /**
+     * Get total task count
+     */
+    get taskCount(): number;
+    /**
+     * Delete a task
+     */
+    deleteTask(taskId: string): boolean;
+    /**
+     * Clean up expired tasks
+     */
+    cleanupExpiredTasks(): number;
+    /**
+     * Clear all tasks
+     */
+    clearAllTasks(): void;
+    /**
+     * Destroy the task manager
+     */
+    destroy(): void;
+    /**
+     * Get the underlying task store
+     */
+    getStore(): TaskStore;
+}
+/**
+ * Create a new TaskManager instance
+ */
+export declare function createTaskManager(config?: TaskManagerConfig): TaskManager;
+export type { A2ATask, TaskHistoryEntry, TaskError, TaskMetadata, } from './task-store.js';
+//# sourceMappingURL=task-manager.d.ts.map

package/v3/dist/adapters/a2a/tasks/task-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-manager.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/tasks/task-manager.ts"],"names":[],"mappings":"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"}