/**
 * @fileoverview Core result types for AFD commands
 *
 * The CommandResult interface is the standard return type for all AFD commands.
 * It includes both core fields (success, data, error) and UX-enabling fields
 * (confidence, reasoning, sources, etc.) that help build user trust.
 */
import type { CommandError } from './errors.js';
import type { Alternative, PlanStep, Source, Warning } from './metadata.js';
/**
 * Standard result type for all AFD commands.
 *
 * @template T - The type of the primary result data
 *
 * @example
 * ```typescript
 * const result: CommandResult<Document> = {
 *   success: true,
 *   data: { id: 'doc-123', title: 'My Document' },
 *   confidence: 0.95,
 *   reasoning: 'Document created successfully with all required fields'
 * };
 * ```
 */
export interface CommandResult<T = unknown> {
    /**
     * Whether the command executed successfully.
     *
     * - `true`: Command completed without errors, `data` contains the result
     * - `false`: Command failed, `error` contains details
     */
    success: boolean;
    /**
     * The primary result data when `success` is `true`.
     * The type varies by command.
     */
    data?: T;
    /**
     * Error information when `success` is `false`.
     * Contains code, message, and recovery suggestions.
     */
    error?: CommandError;
    /**
     * Agent's confidence in this result (0-1).
     *
     * Enables: Confidence indicators in UI
     *
     * Guidelines:
     * - 0.9 - 1.0: Very high confidence, auto-apply safe
     * - 0.7 - 0.9: High confidence, show as recommendation
     * - 0.5 - 0.7: Moderate confidence, require confirmation
     * - < 0.5: Low confidence, show alternatives prominently
     */
    confidence?: number;
    /**
     * Explanation of why this result was produced.
     *
     * Enables: Transparency ("why did the agent do this?")
     *
     * @example "Selected this option because it matches your stated preference for brevity"
     */
    reasoning?: string;
    /**
     * Information sources used to produce this result.
     *
     * Enables: Source attribution, verification, trust
     *
     * @example [{ type: 'document', id: 'doc-123', title: 'Style Guide' }]
     */
    sources?: Source[];
    /**
     * Steps in a multi-step operation.
     *
     * Enables: Plan visualization, progress tracking
     *
     * @example [{ id: '1', action: 'fetch', status: 'complete' }, ...]
     */
    plan?: PlanStep[];
    /**
     * Other options the agent considered.
     *
     * Enables: Alternative exploration, user choice
     *
     * @example [{ data: alternativeResult, reason: 'More formal tone', confidence: 0.7 }]
     */
    alternatives?: Alternative<T>[];
    /**
     * Non-fatal issues to surface to the user.
     *
     * Enables: Proactive transparency about potential problems
     *
     * @example [{ code: 'OUTDATED_SOURCE', message: 'Style guide is 6 months old' }]
     */
    warnings?: Warning[];
    /**
     * Helpful next steps for the user.
     *
     * Enables: Guided exploration, discoverability
     *
     * @example ['Try todo-list to see all items', 'Use todo-update to modify']
     */
    suggestions?: string[];
    /**
     * Execution metadata for debugging and monitoring.
     */
    metadata?: ResultMetadata;
    /**
     * Undo command name (for remote/serializable undo).
     * When present, indicates this operation can be reversed by calling the specified command.
     */
    undoCommand?: string;
    /**
     * Arguments to pass to the undo command.
     * Used with `undoCommand` for serialization over MCP (functions can't serialize).
     */
    undoArgs?: Record<string, unknown>;
}
/**
 * Execution metadata included in command results.
 */
export interface ResultMetadata {
    /** Time taken to execute the command in milliseconds */
    executionTimeMs?: number;
    /** Version of the command that produced this result */
    commandVersion?: string;
    /** Unique trace ID for debugging and correlation */
    traceId?: string;
    /** Timestamp when the command was executed */
    timestamp?: string;
    /** Additional arbitrary metadata */
    [key: string]: unknown;
}
/**
 * Create a successful command result.
 *
 * @param data - The result data
 * @param options - Additional UX-enabling fields
 * @returns A CommandResult with success: true
 */
export declare function success<T>(data: T, options?: Omit<CommandResult<T>, 'success' | 'data' | 'error'>): CommandResult<T>;
/**
 * Create a failed command result.
 *
 * @param error - The error details
 * @param options - Additional fields (e.g., warnings, metadata, alternatives)
 * @returns A CommandResult with success: false
 */
export declare function failure<T = never>(error: CommandError, options?: Omit<CommandResult<T>, 'success' | 'data' | 'error'>): CommandResult<T>;
/**
 * Create a failed command result from code and message.
 *
 * Convenience wrapper that creates a CommandError and wraps it in failure().
 * Matches the Python error() function signature.
 *
 * @param code - Machine-readable error code (SCREAMING_SNAKE_CASE)
 * @param message - Human-readable error description
 * @param options - Additional error fields
 * @returns A CommandResult with success: false
 */
export declare function error<T = unknown>(code: string, message: string, options?: {
    suggestion?: string;
    retryable?: boolean;
    details?: Record<string, unknown>;
}): CommandResult<T>;
/**
 * Type guard to check if a result is successful.
 *
 * Depends only on `success === true`, so a void command's `success(undefined)`
 * is a success. The narrowed `data` has the result's own type `T`, which is
 * `undefined` (or `void`) for commands that return no data.
 */
export declare function isSuccess<T>(result: CommandResult<T>): result is CommandResult<T> & {
    success: true;
    data: T;
};
/**
 * Type guard to check if a result is a failure.
 *
 * Depends only on `success === false`, as {@link isSuccess} depends only on
 * `success === true`, so every result is exactly one of the two. `{ success:
 * false }` without an `error` is a failure too.
 *
 * As `isSuccess` narrows `data` to `T` without checking that it is present,
 * `isFailure` narrows `error` to `CommandError` without checking it. Results
 * built with `failure()` always carry one; for results from an untrusted
 * peer, read it defensively (`result.error?.code`).
 */
export declare function isFailure<T>(result: CommandResult<T>): result is CommandResult<T> & {
    success: false;
    error: CommandError;
};
//# sourceMappingURL=result.d.ts.map