@dexwox-labs/a2a-core/dist/utils/task.d.ts

Core types, validation and telemetry for Google's Agent-to-Agent (A2A) protocol - shared foundation for client and server implementations

/**
 * @module TaskUtils
 * @description Utilities for working with tasks in the A2A protocol
 *
 * This module provides utility functions for validating and managing tasks
 * in the A2A protocol. Tasks are the primary unit of work in the protocol and
 * follow a specific state machine with defined transitions.
 */
import type { Task, TaskState, TaskTransition } from '../types/a2a-protocol';
/**
 * Error codes specific to task operations
 *
 * These error codes are used to identify specific issues that can occur
 * when working with tasks, such as invalid state transitions or missing
 * required properties.
 */
export declare enum TaskErrorCode {
    /** Error code when a task state transition is invalid (-32070) */
    InvalidTransition = -32070,
    /** Error code when a task is missing a required ID (-32071) */
    MissingTaskId = -32071,
    /** Error code when a task state is invalid (-32072) */
    InvalidState = -32072
}
/**
 * Validates that a task state transition is allowed
 *
 * This function checks if a proposed state transition follows the rules of the
 * task state machine. It throws an error if the transition is not allowed.
 *
 * @param current - Current task state
 * @param next - Proposed next state
 * @throws {A2AError} If the transition is invalid
 *
 * @example
 * ```typescript
 * try {
 *   // Valid transition
 *   validateTransition('submitted', 'working');
 *   console.log('Transition is valid');
 *
 *   // Invalid transition
 *   validateTransition('completed', 'working');
 * } catch (error) {
 *   console.error('Invalid transition:', error.message);
 *   // Output: Invalid transition: Invalid transition from completed to working
 * }
 * ```
 */
export declare function validateTransition(current: TaskState, next: TaskState): void;
/**
 * Validates that a task has all required properties and a valid state
 *
 * This function checks that a task has a valid ID and state. It throws
 * appropriate errors if validation fails, which can be caught and handled
 * by the caller.
 *
 * @param task - Task object to validate
 * @throws {A2AError} If validation fails, with specific error codes
 *
 * @example
 * ```typescript
 * try {
 *   // Valid task
 *   validateTask({
 *     id: 'task-123',
 *     name: 'Example Task',
 *     status: 'working',
 *     createdAt: new Date().toISOString(),
 *     updatedAt: new Date().toISOString()
 *   });
 *   console.log('Task is valid');
 *
 *   // This would throw an error
 *   validateTask({
 *     name: 'Invalid Task', // Missing ID
 *     status: 'working',
 *     createdAt: new Date().toISOString(),
 *     updatedAt: new Date().toISOString()
 *   });
 * } catch (error) {
 *   console.error('Validation failed:', error.message);
 * }
 * ```
 */
export declare function validateTask(task: Task): void;
/**
 * Creates a new task transition record
 *
 * This function creates a transition record that documents a change in task state.
 * Transition records include the starting state, ending state, timestamp, and an
 * optional reason for the transition.
 *
 * @param from - Starting task state
 * @param to - Ending task state
 * @param reason - Optional reason for the transition
 * @returns A new transition object with timestamp
 *
 * @example
 * ```typescript
 * // Create a transition record when a task is completed
 * const transition = createTransition('working', 'completed');
 * console.log(transition);
 * // Output: {
 * //   from: 'working',
 * //   to: 'completed',
 * //   timestamp: '2023-05-26T12:34:56.789Z'
 * // }
 *
 * // Create a transition record with a reason
 * const failedTransition = createTransition(
 *   'working',
 *   'failed',
 *   'API request timeout'
 * );
 * console.log(failedTransition);
 * // Output: {
 * //   from: 'working',
 * //   to: 'failed',
 * //   timestamp: '2023-05-26T12:35:12.345Z',
 * //   reason: 'API request timeout'
 * // }
 * ```
 */
export declare function createTransition(from: TaskState, to: TaskState, reason?: string): TaskTransition;
//# sourceMappingURL=task.d.ts.map