/**
 * Streaming Handler Module
 *
 * Handles message streaming and accumulation for the agent.
 * Implements delta reduction (messageReducer pattern), content sanitization,
 * token counting during streaming, and tool call extraction from content.
 *
 * @module agent/streaming
 */
import { CodeBuddyToolCall } from '../../codebuddy/client.js';
import { sanitizeLLMOutput, extractCommentaryToolCalls, ExtractedToolCall } from '../../utils/sanitize.js';
/**
 * Configuration options for the StreamingHandler.
 */
export interface StreamingConfig {
    /** Whether to sanitize LLM output (remove control tokens). Default: true */
    sanitizeOutput?: boolean;
    /** Whether to extract commentary-style tool calls from content. Default: true */
    extractToolCalls?: boolean;
    /** Whether to track token counts during streaming. Default: true */
    trackTokens?: boolean;
    /** Model name for token counting. Default: 'gpt-4' */
    model?: string;
    /** Minimum interval (ms) between token count updates. Default: 500 */
    tokenUpdateInterval?: number;
}
/**
 * Represents a raw chunk of streaming data from the LLM API.
 * This is the raw chunk format from OpenAI-compatible APIs.
 * Note: This is distinct from the agent's StreamingChunk in types.ts
 * which is the processed chunk yielded by the agent.
 */
export interface RawStreamingChunk {
    /** Unique identifier for the chunk */
    id?: string;
    /** Object type (usually 'chat.completion.chunk') */
    object?: string;
    /** Timestamp of creation */
    created?: number;
    /** Model that generated the chunk */
    model?: string;
    /** Array of choices containing delta updates */
    choices?: Array<{
        /** Index of the choice */
        index?: number;
        /** Delta update containing incremental content */
        delta?: {
            /** Role of the message (usually only in first chunk) */
            role?: string;
            /** Content delta (text fragment) */
            content?: string;
            /** Reasoning/thinking content delta (Claude thinking, Grok reasoning) */
            reasoning_content?: string;
            /** Alternative field name for reasoning (some providers) */
            reasoning?: string;
            /** Tool calls delta (incremental tool call data) */
            tool_calls?: Array<{
                /** Index of the tool call in the array */
                index?: number;
                /** Unique identifier for the tool call */
                id?: string;
                /** Type of tool call (usually 'function') */
                type?: string;
                /** Function details */
                function?: {
                    /** Function name (usually only in first chunk for this tool) */
                    name?: string;
                    /** Arguments string (accumulated across chunks) */
                    arguments?: string;
                };
            }>;
        };
        /** Reason for finishing (null while streaming) */
        finish_reason?: string | null;
    }>;
    /** Usage information (may be provided at end of stream) */
    usage?: {
        prompt_tokens?: number;
        completion_tokens?: number;
        total_tokens?: number;
    };
}
/**
 * Result of processing a streaming chunk.
 */
export interface ProcessedChunk {
    /** Sanitized content to display (may be empty if only control tokens) */
    displayContent: string;
    /** Raw content before sanitization */
    rawContent: string;
    /** Whether new tool calls were detected */
    hasNewToolCalls: boolean;
    /** Current accumulated tool calls (if any) */
    toolCalls?: CodeBuddyToolCall[];
    /** Current token count estimate */
    tokenCount?: number;
    /** Whether a token count update should be emitted */
    shouldEmitTokenCount: boolean;
    /** Reasoning/thinking content delta (if present in this chunk) */
    reasoningContent?: string;
}
/**
 * Result of tool call extraction from accumulated content.
 */
export interface ExtractedToolCallsResult {
    /** Tool calls in OpenAI format */
    toolCalls: CodeBuddyToolCall[];
    /** Content with tool call patterns removed */
    remainingContent: string;
}
/**
 * Accumulated message state during streaming.
 */
export interface AccumulatedMessage {
    /** Role of the message */
    role?: string;
    /** Accumulated content string */
    content?: string;
    /** Accumulated tool calls */
    tool_calls?: CodeBuddyToolCall[];
    /** Any additional fields from the API */
    [key: string]: unknown;
}
/**
 * StreamingHandler manages the accumulation and processing of streaming
 * responses from LLM APIs. It handles:
 *
 * - Delta reduction: Accumulating incremental updates into a complete message
 * - Content sanitization: Removing LLM control tokens from output
 * - Token counting: Real-time estimation of token usage
 * - Tool call extraction: Detecting tool calls from both native format and commentary patterns
 *
 * @example
 * ```typescript
 * const handler = new StreamingHandler({ sanitizeOutput: true });
 *
 * for await (const chunk of stream) {
 *   const result = handler.accumulateChunk(chunk);
 *   if (result.displayContent) {
 *     console.log(result.displayContent);
 *   }
 *   if (result.hasNewToolCalls) {
 *     console.log('Tool calls:', result.toolCalls);
 *   }
 * }
 *
 * const finalMessage = handler.getAccumulatedMessage();
 * handler.reset();
 * ```
 */
export declare class StreamingHandler {
    private config;
    private accumulatedMessage;
    private accumulatedRawContent;
    private accumulatedReasoningContent;
    private tokenCounter;
    private lastTokenUpdate;
    private toolCallsYielded;
    /**
     * Creates a new StreamingHandler instance.
     *
     * @param config - Configuration options for the handler
     */
    constructor(config?: StreamingConfig);
    /**
     * Processes a streaming chunk and accumulates it into the message.
     *
     * @param chunk - The streaming chunk from the API
     * @returns Processed chunk with display content and metadata
     */
    accumulateChunk(chunk: RawStreamingChunk): ProcessedChunk;
    /**
     * Extracts tool calls from commentary patterns in the accumulated content.
     * This handles models that don't support native OpenAI tool calls.
     *
     * Supported patterns:
     * - "commentary to=tool_name {...}"
     * - "commentary to=tool_name <|constrain|>json<|message|>{...}"
     * - Direct tool patterns: "web_search {...}"
     *
     * @returns Extracted tool calls and remaining content
     */
    extractToolCalls(): ExtractedToolCallsResult;
    /**
     * Gets the current accumulated message state.
     *
     * @returns The accumulated message with all processed content and tool calls
     */
    getAccumulatedMessage(): AccumulatedMessage;
    /**
     * Gets the raw accumulated content before sanitization.
     * Useful for tool call extraction that needs the original patterns.
     *
     * @returns The raw accumulated content string
     */
    getRawContent(): string;
    /**
     * Gets the sanitized accumulated content.
     *
     * @returns The sanitized content string
     */
    getSanitizedContent(): string;
    /**
     * Gets the current token count estimate.
     *
     * @returns Token count or undefined if tracking is disabled
     */
    getTokenCount(): number | undefined;
    /**
     * Checks if tool calls have been yielded/detected.
     *
     * @returns True if tool calls have been detected and yielded
     */
    hasYieldedToolCalls(): boolean;
    /**
     * Resets the handler state for a new streaming session.
     * Call this before processing a new response stream.
     */
    reset(): void;
    /**
     * Disposes of resources used by the handler.
     * Call this when the handler is no longer needed.
     */
    dispose(): void;
}
export { sanitizeLLMOutput, extractCommentaryToolCalls };
export type { ExtractedToolCall };
