import { AutoBeEvent } from "../events/AutoBeEvent";
import { AutoBeUserConversateContent } from "../events/contents/AutoBeUserConversateContent";
import { AutoBeHistory } from "../histories/AutoBeHistory";
import { AutoBePhase } from "../histories/AutoBePhase";
import { IAutoBeTokenUsageJson } from "../json";
import { IAutoBeGetFilesOptions } from "./IAutoBeGetFilesOptions";

export interface IAutoBeAgent {
  /**
   * Engages in conversation with the agent to drive the vibe coding process.
   *
   * Accepts user input in multiple formats including simple text strings,
   * single multimodal content items, or arrays of content supporting text,
   * images, file uploads, and audio input. The conversation serves as the
   * primary interface for expressing requirements, providing feedback, and
   * guiding the development process through natural language interaction.
   *
   * The agent analyzes the conversation context to determine appropriate
   * actions, potentially activating specialized agents (Analyze, Database,
   * Interface, Test, Realize) through function calling based on user needs.
   * Real-time progress events are fired through registered listeners while the
   * conversation processes.
   *
   * Returns all history records generated during this conversation turn,
   * including user messages, assistant responses, and any development
   * activities triggered by the interaction. This enables clients to track both
   * conversational flow and development progress.
   *
   * @param content User input as text, single content item, or multimodal array
   * @returns Promise resolving to array of history records from this
   *   conversation
   */
  conversate(
    content:
      | string
      | AutoBeUserConversateContent
      | AutoBeUserConversateContent[],
  ): Promise<AutoBeHistory[]>;

  /**
   * Retrieves all generated files from the current development session.
   *
   * Transforms the complete conversation-driven development process into a
   * comprehensive collection of deployable artifacts, including requirements
   * documentation, database schemas, API specifications, NestJS implementation
   * code, and test suites. The generated files represent a fully functional
   * backend application ready for immediate deployment or further
   * customization.
   *
   * The method produces a meticulously organized project structure that
   * reflects professional software development standards. Requirements analysis
   * documents capture and formalize your conversational input into structured
   * technical specifications, providing clear traceability from user intent to
   * final implementation. Database artifacts include Prisma schemas with
   * precise type definitions, relationships, and constraints, along with
   * migration files for proper database initialization and evolution.
   *
   * The API layer emerges through comprehensive OpenAPI specifications
   * documenting every endpoint, request format, response structure, and error
   * condition. Generated NestJS controllers, DTOs, and service classes
   * implement these specifications with TypeScript's strong typing system
   * providing compile-time safety. Quality assurance is embedded throughout
   * with complete test suites covering both unit and end-to-end scenarios.
   *
   * The database configuration specified through the `dbms` option
   * fundamentally shapes the entire generated codebase. PostgreSQL
   * configuration produces production-ready code with robust connection pooling
   * and enterprise-grade optimizations, while SQLite generates lightweight code
   * perfect for local development and rapid prototyping without external
   * dependencies.
   *
   * All artifacts maintain perfect consistency across the chosen database
   * system, from Prisma configurations and connection strings to Docker compose
   * files and environment templates. This deep integration ensures immediate
   * deployment compatibility without manual configuration adjustments.
   *
   * @param options Configuration specifying the target database management
   *   system and other code generation preferences that influence the structure
   *   and characteristics of the generated project files
   * @returns Promise resolving to key-value pairs mapping logical file paths to
   *   complete file contents for all generated development artifacts, ready for
   *   immediate file system operations, build integration, or deployment
   *   workflows
   */
  getFiles(
    options?: Partial<IAutoBeGetFilesOptions>,
  ): Promise<Record<string, string>>;

  /**
   * Retrieves the complete conversation and development history.
   *
   * Returns the chronologically ordered record of all events from the current
   * session including user messages, assistant responses, development phase
   * activities, progress events, and completion notifications. This
   * comprehensive history enables conversation replay, development process
   * analysis, and understanding of how requirements evolved into working
   * software.
   *
   * The history provides complete transparency into the vibe coding process,
   * showing both conversational interactions and behind-the-scenes development
   * activities. This information is valuable for debugging, process
   * improvement, and educational purposes to understand the agent's
   * decision-making process.
   *
   * @returns Chronologically ordered array of all history records including
   *   messages, events, and development activities
   */
  getHistories(): AutoBeHistory[];

  /**
   * Retrieves comprehensive AI token usage statistics for the current session.
   *
   * Returns detailed breakdown of token consumption across all specialized
   * agents and processing phases, enabling cost monitoring, performance
   * analysis, and optimization of AI resource utilization. Statistics include
   * aggregate totals and component-specific breakdowns with input/output
   * categorization, caching analysis, and reasoning token tracking.
   *
   * Token usage data is essential for understanding the computational costs of
   * different development phases and optimizing AI efficiency. The breakdown
   * helps identify which agents or operations consume the most resources,
   * enabling targeted optimization efforts while maintaining development
   * quality.
   *
   * @returns Comprehensive token usage statistics with detailed breakdowns by
   *   agent, operation type, and consumption category
   */
  getTokenUsage(): IAutoBeTokenUsageJson;

  /**
   * Retrieves the current development phase in the vibe coding pipeline.
   *
   * Returns the active phase of the AutoBE development process, indicating
   * which agent is currently executing or which stage of backend generation is
   * in progress. This information is useful for tracking overall pipeline
   * progress, displaying phase-specific UI elements, and coordinating
   * multi-phase operations.
   *
   * The phase information updates in real-time as the agent progresses through
   * the waterfall development model, transitioning from analyze through
   * database, interface, test, and realize phases. When no phase is active
   * (before starting or after completion), returns null.
   *
   * @returns Current AutoBePhase enum value indicating the active development
   *   phase, or null when no phase is currently executing
   */
  getPhase(): AutoBePhase | null;

  /**
   * Registers an event listener for specific development phase events.
   *
   * Enables client applications to receive real-time notifications about
   * conversation flow, development progress, and completion events throughout
   * the vibe coding pipeline. Event listeners provide visibility into agent
   * activities and enable responsive user interfaces that can display progress,
   * handle artifacts, and provide feedback.
   *
   * The type-safe event system ensures that listeners receive properly typed
   * events corresponding to their registration type, enabling robust event
   * handling without runtime type issues. Multiple listeners can be registered
   * for the same event type to support complex notification requirements.
   *
   * @param type Event type to listen for (e.g., "analyzeComplete",
   *   "databaseStart")
   * @param listener Callback function that receives the typed event when fired
   * @returns The agent instance for method chaining
   */
  on<Type extends AutoBeEvent.Type>(
    type: Type,
    listener: (event: AutoBeEvent.Mapper[Type]) => Promise<void> | void,
  ): this;

  /**
   * Unregisters a previously registered event listener.
   *
   * Removes the specified event listener from the agent's notification system,
   * stopping further event notifications for that particular listener function.
   * This is useful for cleanup, dynamic listener management, or when components
   * no longer need to receive specific event notifications.
   *
   * The listener function reference must exactly match the function that was
   * originally registered with {@link on} for successful removal. If no matching
   * listener is found, the operation has no effect.
   *
   * @param type Event type the listener was registered for
   * @param listener The exact listener function reference to remove
   * @returns The agent instance for method chaining
   */
  off<Type extends AutoBeEvent.Type>(
    type: Type,
    listener: (event: AutoBeEvent.Mapper[Type]) => Promise<void> | void,
  ): this;
}