/**
 * Stream Event Types and Parser Interface
 *
 * Standardized events emitted by all provider stream parsers.
 * Each provider's NDJSON output is normalized to these common events.
 */

/** Initialization event - emitted at stream start, may contain session ID */
export interface StreamInitEvent {
  type: 'init';
  sessionId?: string;
}

/** Text delta - chunk of assistant text output */
export interface StreamTextDeltaEvent {
  type: 'text_delta';
  text: string;
}

/** Tool use started - agent is calling a tool */
export interface StreamToolUseStartEvent {
  type: 'tool_use_start';
  name: string;
  id: string;
}

/** Tool result received */
export interface StreamToolResultEvent {
  type: 'tool_result';
  id: string;
}

/** Turn ended - assistant stopped responding */
export interface StreamTurnEndEvent {
  type: 'turn_end';
  stopReason: string;
}

/** Final result - emitted at stream end with complete output */
export interface StreamResultEvent {
  type: 'result';
  text: string;
  sessionId?: string;
  costUsd?: number;
  /** True when the CLI returned an error result (e.g. auth failure, usage limit) */
  isError?: boolean;
}

/** Error event */
export interface StreamErrorEvent {
  type: 'error';
  message: string;
}

/** Union of all stream event types */
export type StreamEvent =
  | StreamInitEvent
  | StreamTextDeltaEvent
  | StreamToolUseStartEvent
  | StreamToolResultEvent
  | StreamTurnEndEvent
  | StreamResultEvent
  | StreamErrorEvent;

/**
 * Stream Parser Interface
 *
 * Implementations parse provider-specific NDJSON into standardized events.
 */
export interface StreamParser {
  /** Provider name this parser handles */
  readonly provider: string;

  /** Parse a single NDJSON line into zero or more standardized events */
  parseLine(line: string): StreamEvent[];

  /** Signal end of stream - allows parser to emit final events */
  end(): StreamEvent[];
}
