/**
 * Copyright 2025 Vybestack LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * Universal content representation that is provider-agnostic.
 * All conversation content is represented as blocks within a speaker's turn.
 */
export interface IContent {
    /**
     * Who is speaking in this content
     * - 'human': The user
     * - 'ai': The AI assistant
     * - 'tool': A tool/function response
     */
    speaker: 'human' | 'ai' | 'tool';
    /**
     * Array of content blocks that make up this message.
     * A message can contain multiple blocks of different types.
     */
    blocks: ContentBlock[];
    /**
     * Optional metadata for the content
     */
    metadata?: ContentMetadata;
}
/**
 * Metadata associated with content
 */
export interface ContentMetadata {
    /** When this content was created */
    timestamp?: number;
    /** Which model generated this (for AI responses) */
    model?: string;
    /** Token usage statistics */
    usage?: UsageStats;
    /** Unique identifier for this content */
    id?: string;
    /** Provider that generated this content */
    provider?: string;
    /** Whether this is a summary of previous messages */
    isSummary?: boolean;
    /** Additional provider-specific metadata */
    providerMetadata?: Record<string, unknown>;
    /** Whether this content is synthetic (auto-generated) */
    synthetic?: boolean;
    /** Reason for synthetic content generation */
    reason?: string;
}
export interface UsageStats {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
    cachedTokens?: number;
    cacheCreationTokens?: number;
    cacheMissTokens?: number;
    cache_read_input_tokens?: number;
    cache_creation_input_tokens?: number;
}
/**
 * Union type of all possible content blocks
 */
export type ContentBlock = TextBlock | ToolCallBlock | ToolResponseBlock | MediaBlock | ThinkingBlock | CodeBlock;
/**
 * Regular text content
 */
export interface TextBlock {
    type: 'text';
    text: string;
}
/**
 * AI calling a tool/function
 */
export interface ToolCallBlock {
    type: 'tool_call';
    /** Unique identifier for this tool call */
    id: string;
    /** Name of the tool being called */
    name: string;
    /** Parameters passed to the tool (must be JSON-serializable) */
    parameters: unknown;
    /** Optional description of what this tool call is intended to do */
    description?: string;
}
/**
 * Response from a tool/function call
 */
export interface ToolResponseBlock {
    type: 'tool_response';
    /** References the ToolCallBlock.id this is responding to */
    callId: string;
    /** The tool that generated this response */
    toolName: string;
    /** Result from the tool (must be JSON-serializable) */
    result: unknown;
    /** Error message if the tool call failed */
    error?: string;
    /** Whether this response completes the tool call */
    isComplete?: boolean;
}
/**
 * Media content (images, files, etc.)
 */
export interface MediaBlock {
    type: 'media';
    /** MIME type of the media */
    mimeType: string;
    /** Either a URL or base64-encoded data */
    data: string;
    /** Whether data is a URL or base64 */
    encoding: 'url' | 'base64';
    /** Optional caption or alt text */
    caption?: string;
    /** Original filename if applicable */
    filename?: string;
}
/**
 * Thinking/reasoning content (for models that support it)
 * @plan PLAN-20251202-THINKING.P03
 * @requirement REQ-THINK-001.1, REQ-THINK-001.2
 */
export interface ThinkingBlock {
    type: 'thinking';
    /** The thinking/reasoning text */
    thought: string;
    /** Whether this thinking should be hidden from the user */
    isHidden?: boolean;
    /** Source field name for round-trip serialization */
    sourceField?: 'reasoning_content' | 'thinking' | 'thought' | 'think_tags';
    /** Signature for Anthropic extended thinking */
    signature?: string;
}
/**
 * Code content with syntax highlighting support
 */
export interface CodeBlock {
    type: 'code';
    /** The code content */
    code: string;
    /** Programming language for syntax highlighting */
    language?: string;
    /** Optional filename this code is from/for */
    filename?: string;
    /** Whether this code was executed */
    executed?: boolean;
    /** Execution result if executed */
    executionResult?: unknown;
}
/**
 * Helper type guards for content blocks
 */
export declare const ContentBlockGuards: {
    isTextBlock: (block: ContentBlock) => block is TextBlock;
    isToolCallBlock: (block: ContentBlock) => block is ToolCallBlock;
    isToolResponseBlock: (block: ContentBlock) => block is ToolResponseBlock;
    isMediaBlock: (block: ContentBlock) => block is MediaBlock;
    isThinkingBlock: (block: ContentBlock) => block is ThinkingBlock;
    isCodeBlock: (block: ContentBlock) => block is CodeBlock;
};
/**
 * Helper to create IContent instances
 */
export declare const ContentFactory: {
    createUserMessage: (text: string, metadata?: ContentMetadata) => IContent;
    createAIMessage: (blocks: ContentBlock[], metadata?: ContentMetadata) => IContent;
    createToolResponse: (callId: string, toolName: string, result: unknown, error?: string, metadata?: ContentMetadata) => IContent;
};
/**
 * Validation helpers
 */
export declare const ContentValidation: {
    /**
     * Check if content has meaningful content (not empty)
     */
    hasContent: (content: IContent) => boolean;
    /**
     * Check if content is valid for inclusion in history
     */
    isValid: (content: IContent) => boolean;
};
