/**
 * SmartPerfetto Agent Protocol Types
 *
 * Phase 2: Agent-ification with Skills as Tools
 *
 * This file defines the core types for the AI Agents system.
 * Agents wrap existing Skills as "tools" they can invoke through AI reasoning.
 */
import { Finding } from '../types';
import { SkillDefinition, SkillExecutionResult } from '../../services/skillEngine';
import { DataEnvelope } from '../../types/dataContract';
/**
 * AgentTool - Wraps a Skill as a tool that an Agent can invoke
 *
 * Instead of replacing Skills, we wrap them as tools that Agents can reason about
 * and decide when to invoke.
 */
export interface AgentTool {
    /** Unique tool name */
    name: string;
    /** Human-readable description for LLM to understand when to use this tool */
    description: string;
    /** Optional skill ID this tool maps to */
    skillId?: string;
    /** Tool category for organization */
    category: 'frame' | 'cpu' | 'memory' | 'binder' | 'startup' | 'interaction' | 'system' | 'general';
    /** Required parameters */
    parameters?: AgentToolParameter[];
    /** Execute the tool */
    execute: (params: Record<string, any>, context: AgentToolContext) => Promise<AgentToolResult>;
}
/**
 * Tool parameter definition
 */
export interface AgentToolParameter {
    name: string;
    type: 'string' | 'number' | 'boolean' | 'timestamp' | 'duration' | 'array';
    required: boolean;
    description: string;
    default?: any;
}
/**
 * Context passed to tools during execution
 */
export interface AgentToolContext {
    sessionId: string;
    traceId: string;
    traceProcessorService?: any;
    /** AI service for AI-powered tools */
    aiService?: {
        chat: (prompt: string) => Promise<string>;
    };
    /** Package name being analyzed */
    packageName?: string;
    /** Time range for analysis (string for precision-safe ns timestamps) */
    timeRange?: {
        start: number | string;
        end: number | string;
    };
    /** Additional context data */
    additionalContext?: Record<string, any>;
}
/**
 * Result from tool execution
 */
export interface AgentToolResult {
    success: boolean;
    data?: any;
    findings?: Finding[];
    error?: string;
    executionTimeMs: number;
    /** Layered result data from skill execution */
    layeredResult?: any;
    /** DataEnvelope(s) for SSE data events */
    dataEnvelopes?: DataEnvelope[];
    /** Optional metadata for debugging/tracking (e.g., dynamic SQL details) */
    metadata?: Record<string, any>;
}
/**
 * Task assigned to an agent
 */
export interface AgentTask {
    /** Unique task ID */
    id: string;
    /** Task description */
    description: string;
    /** Agent ID to handle this task */
    targetAgentId: string;
    /** Priority (1 = highest) */
    priority: number;
    /** Task context */
    context: AgentTaskContext;
    /** Dependencies - task IDs that must complete first */
    dependencies: string[];
    /** Task timeout in ms */
    timeout?: number;
    /** Created timestamp */
    createdAt: number;
}
/**
 * Context for a task
 */
export interface AgentTaskContext {
    /** Original user query */
    query: string;
    /** Parsed intent */
    intent?: {
        primaryGoal: string;
        aspects: string[];
    };
    /** Domain of the task */
    domain?: string;
    /** Evidence or metrics required */
    evidenceNeeded?: string[];
    /** Hypothesis to investigate */
    hypothesis?: Hypothesis;
    /** Time range to focus on (string for precision-safe ns timestamps) */
    timeRange?: {
        start: number | string;
        end: number | string;
    };
    /** Previous findings relevant to this task */
    relevantFindings?: Finding[];
    /** Additional context data */
    additionalData?: Record<string, any>;
}
/**
 * A hypothesis about the performance issue
 */
export interface Hypothesis {
    /** Unique hypothesis ID */
    id: string;
    /** Hypothesis description */
    description: string;
    /** Confidence level (0-1) */
    confidence: number;
    /** Status */
    status: 'proposed' | 'investigating' | 'confirmed' | 'rejected';
    /** Evidence supporting this hypothesis */
    supportingEvidence: Evidence[];
    /** Evidence against this hypothesis */
    contradictingEvidence: Evidence[];
    /** Agent that proposed this hypothesis */
    proposedBy: string;
    /** Agents relevant to investigating this hypothesis */
    relevantAgents?: string[];
    /** Timestamp */
    createdAt: number;
    /** Last updated timestamp */
    updatedAt: number;
}
/**
 * Evidence for or against a hypothesis
 */
export interface Evidence {
    /** Evidence ID */
    id: string;
    /** Description of the evidence */
    description: string;
    /** Source (finding ID, tool result, etc.) */
    source: string;
    /** Type of evidence */
    type: 'finding' | 'metric' | 'observation' | 'inference';
    /** Strength of evidence (0-1) */
    strength: number;
    /** Timestamp of the evidence */
    timestamp?: number;
}
/**
 * Response from an agent after completing a task
 */
export interface AgentResponse {
    /** Agent ID that produced this response */
    agentId: string;
    /** Task ID this response is for */
    taskId: string;
    /** Whether the task was successful */
    success: boolean;
    /** Findings discovered */
    findings: Finding[];
    /** Hypothesis updates */
    hypothesisUpdates?: HypothesisUpdate[];
    /** Questions for other agents */
    questionsForAgents?: InterAgentQuestion[];
    /** Suggestions for further investigation */
    suggestions?: string[];
    /** Confidence in the response */
    confidence: number;
    /** Execution time in ms */
    executionTimeMs: number;
    /** Raw data from tool executions */
    toolResults?: AgentToolResult[];
    /** Reasoning trace */
    reasoning?: ReasoningStep[];
}
/**
 * Update to a hypothesis
 */
export interface HypothesisUpdate {
    hypothesisId: string;
    action: 'support' | 'contradict' | 'confirm' | 'reject' | 'update_confidence';
    evidence?: Evidence;
    newConfidence?: number;
    reason: string;
}
/**
 * Question from one agent to another
 */
export interface InterAgentQuestion {
    /** From agent */
    fromAgent: string;
    /** Target agent */
    toAgent: string;
    /** Question */
    question: string;
    /** Context for the question */
    context?: Record<string, any>;
    /** Priority */
    priority: number;
}
/**
 * A step in the agent's reasoning process
 */
export interface ReasoningStep {
    step: number;
    type: 'observation' | 'analysis' | 'decision' | 'action';
    content: string;
    confidence: number;
    timestamp: number;
}
/**
 * Base configuration for all agents
 */
export interface AgentConfig {
    /** Unique agent ID */
    id: string;
    /** Human-readable name */
    name: string;
    /** Agent domain */
    domain: string;
    /** Description of agent capabilities */
    description: string;
    /** Tools available to this agent */
    tools: AgentTool[];
    /** Maximum iterations for reasoning loop */
    maxIterations: number;
    /** Confidence threshold for conclusions */
    confidenceThreshold: number;
    /** Whether this agent can delegate to other agents */
    canDelegate: boolean;
    /** Agents this agent can delegate to */
    delegateTo?: string[];
}
/**
 * Message sent between agents
 */
export interface AgentMessage {
    /** Unique message ID */
    id: string;
    /** Message type */
    type: 'task' | 'response' | 'question' | 'broadcast' | 'event';
    /** Sender agent ID */
    from: string;
    /** Recipient agent ID (or 'all' for broadcast) */
    to: string;
    /** Message payload */
    payload: any;
    /** Correlation ID for request-response patterns */
    correlationId?: string;
    /** Priority */
    priority: number;
    /** Timestamp */
    timestamp: number;
}
/**
 * Broadcast message to all agents
 */
export interface BroadcastMessage {
    /** Message type */
    type: 'hypothesis_proposed' | 'evidence_found' | 'conclusion_reached' | 'focus_shift';
    /** Payload */
    payload: any;
    /** Sender agent ID */
    from: string;
    /** Timestamp */
    timestamp: number;
}
/**
 * Trace-level configuration detected from the trace file.
 * Populated by vsync_config skill at the start of analysis.
 *
 * For VRR/LTPO devices, refresh rate varies dynamically.
 * Use `dominantRefreshRateHz` for most jank calculations.
 */
export interface TraceConfig {
    /** VSync period in nanoseconds (based on dominant refresh rate) */
    vsyncPeriodNs?: number;
    /** Refresh rate in Hz (dominant rate for VRR devices) */
    refreshRateHz?: number;
    /** VSync period in milliseconds (convenience) */
    vsyncPeriodMs?: number;
    /** Data source for vsync detection */
    vsyncSource?: string;
    /** Whether VRR (Variable Refresh Rate) is detected */
    isVRR?: boolean;
    /** VRR mode details if detected */
    vrrMode?: 'VRR_ACTIVE' | 'VRR_LIMITED' | 'FIXED_RATE';
    /** Minimum frame budget in ms (for strictest jank detection, use maxRefreshRateHz) */
    minFrameBudgetMs?: number;
    /** Maximum frame budget in ms (for most lenient detection, use minRefreshRateHz) */
    maxFrameBudgetMs?: number;
}
/**
 * Shared context accessible by all agents in a session
 */
export interface SharedAgentContext {
    /** Session ID */
    sessionId: string;
    /** Trace ID */
    traceId: string;
    /** All proposed hypotheses */
    hypotheses: Map<string, Hypothesis>;
    /** Confirmed findings from all agents */
    confirmedFindings: Finding[];
    /** Current focus time range (string for precision-safe ns timestamps) */
    focusedTimeRange?: {
        start: number | string;
        end: number | string;
    };
    /** Investigation path - trace of agent interactions */
    investigationPath: InvestigationStep[];
    /** Global metrics and statistics */
    globalMetrics?: Record<string, any>;
    /** User-provided context */
    userContext?: Record<string, any>;
    /** Trace-level configuration (vsync, refresh rate, etc.) */
    traceConfig?: TraceConfig;
    /**
     * Jank cause summary aggregated from per-frame analysis.
     * Populated by StrategyExecutor after Stage 2 (frame_analysis).
     * Used by ConclusionGenerator to include structured root cause statistics.
     */
    jankCauseSummary?: import('../core/jankCauseSummarizer').JankCauseSummary;
    /**
     * Per-frame mechanism records captured directly from root_cause step outputs.
     * Unlike findings, these records are not reduced by synthesis deduplication.
     */
    frameMechanismRecords?: import('./jankCause').FrameMechanismRecord[];
}
/**
 * A step in the investigation path
 */
export interface InvestigationStep {
    stepNumber: number;
    agentId: string;
    action: string;
    timestamp: number;
    result: 'success' | 'partial' | 'failed';
    summary: string;
}
/**
 * Create an AgentTool from a SkillDefinition
 */
export declare function createToolFromSkill(skill: SkillDefinition, category: AgentTool['category'], executor: (skillId: string, params: Record<string, any>, context: AgentToolContext) => Promise<SkillExecutionResult>): AgentTool;
/**
 * Create a unique task ID
 */
export declare function createTaskId(): string;
/**
 * Create a unique hypothesis ID
 */
export declare function createHypothesisId(): string;
/**
 * Create a unique message ID
 */
export declare function createMessageId(): string;
//# sourceMappingURL=agentProtocol.d.ts.map