@dexwox-labs/a2a-server/dist/tasks/task-updater.d.ts

TypeScript server implementation for Google's Agent-to-Agent (A2A) protocol - includes Express/WebSocket handlers, request validation and queue management

/**
 * @module TaskUpdater
 * @description Manages task state transitions with validation
 *
 * This module provides functionality for managing task state transitions
 * with validation to ensure that tasks follow the correct lifecycle.
 * It enforces a state machine approach to task status changes.
 */
import { Task, TaskState, TaskTransition } from '@dexwox-labs/a2a-core';
import { TaskManager } from './task-manager';
/**
 * Manages task state transitions with validation
 *
 * The TaskUpdater enforces a state machine approach to task status changes,
 * ensuring that tasks can only transition between valid states. It maintains
 * a history of transitions and provides methods for retrieving this history.
 *
 * @example
 * ```typescript
 * // Create a task updater with a task manager
 * const taskManager = new TaskManager(taskStore);
 * const taskUpdater = new TaskUpdater(taskManager);
 *
 * // Transition a task from 'submitted' to 'working'
 * try {
 *   const updatedTask = await taskUpdater.transitionTask('task-123', 'working');
 *   console.log(`Task is now ${updatedTask.status}`);
 * } catch (error) {
 *   console.error('Failed to transition task:', error.message);
 * }
 * ```
 */
export declare class TaskUpdater {
    /** The task manager used to retrieve and update tasks */
    private readonly taskManager;
    /** Map of valid state transitions for the task state machine */
    private readonly transitions;
    /**
     * Creates a new TaskUpdater
     *
     * @param taskManager - The task manager to use for retrieving and updating tasks
     */
    constructor(taskManager: TaskManager);
    /**
     * Builds the state transition map for the task state machine
     *
     * This defines the valid transitions between task states:
     * - submitted → working, failed
     * - working → completed, failed, canceled
     * - input_required → working, failed, canceled
     * - failed → (terminal state, no transitions)
     * - completed → (terminal state, no transitions)
     * - canceled → (terminal state, no transitions)
     *
     * @returns A map of valid state transitions
     * @internal
     */
    private buildStateTransitionMap;
    /**
     * Transitions a task to a new state
     *
     * This method validates the state transition against the state machine rules,
     * creates a transition record, and updates the task with the new state and
     * transition history.
     *
     * @param taskId - ID of the task to transition
     * @param newState - New state to transition the task to
     * @returns Promise resolving to the updated task
     * @throws InvalidTaskStateError if the transition is not allowed
     *
     * @example
     * ```typescript
     * // Transition a task from 'submitted' to 'working'
     * try {
     *   const task = await taskUpdater.transitionTask('task-123', 'working');
     *   console.log('Task transitioned successfully');
     * } catch (error) {
     *   if (error instanceof InvalidTaskStateError) {
     *     console.error('Invalid state transition:', error.message);
     *   } else {
     *     console.error('Failed to transition task:', error);
     *   }
     * }
     * ```
     */
    transitionTask(taskId: string, newState: TaskState): Promise<Task>;
    /**
     * Checks if a state transition is valid
     *
     * Validates whether a transition from one state to another is allowed
     * according to the state machine rules.
     *
     * @param from - Current state
     * @param to - Target state
     * @returns True if the transition is valid, false otherwise
     * @internal
     */
    private isValidTransition;
    /**
     * Gets the transition history for a task
     *
     * Retrieves the complete history of state transitions for a task,
     * including the from state, to state, and timestamp for each transition.
     *
     * @param taskId - ID of the task
     * @returns Promise resolving to an array of task transitions
     *
     * @example
     * ```typescript
     * // Get the transition history for a task
     * const history = await taskUpdater.getTransitionHistory('task-123');
     * console.log(`Task has undergone ${history.length} transitions`);
     *
     * // Log each transition
     * history.forEach(transition => {
     *   console.log(
     *     `${new Date(transition.timestamp).toLocaleString()}: ` +
     *     `${transition.from} → ${transition.to}`
     *   );
     * });
     * ```
     */
    getTransitionHistory(taskId: string): Promise<TaskTransition[]>;
}
//# sourceMappingURL=task-updater.d.ts.map