@gracker/smartperfetto 1.0.13

package/dist/agent/types.d.ts

@@ -0,0 +1,725 @@
+/**
+ * SmartPerfetto Agent System - Core Types
+ *
+ * This file defines the core interfaces for the Agent-based analysis system.
+ * The architecture follows a layered design:
+ * - Tool Layer: Atomic, deterministic operations (SQL execution, data analysis)
+ * - Expert Agent Layer: Domain-specific analysis agents (Scrolling, Startup, Memory)
+ * - Orchestrator Agent: High-level coordination and reasoning
+ */
+export interface ToolParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'timestamp' | 'array' | 'object';
+    required: boolean;
+    description: string;
+    default?: any;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    category: 'sql' | 'analysis' | 'data' | 'visualization' | 'knowledge';
+    parameters: ToolParameter[];
+    returns: {
+        type: string;
+        description: string;
+    };
+}
+export interface ToolResult<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    executionTimeMs: number;
+    metadata?: Record<string, any>;
+}
+export interface Tool<TParams = any, TResult = any> {
+    definition: ToolDefinition;
+    execute(params: TParams, context: ToolContext): Promise<ToolResult<TResult>>;
+    validate?(params: TParams): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+export interface ToolContext {
+    traceId: string;
+    traceProcessor?: any;
+    traceProcessorService?: any;
+    package?: string;
+    /** AI 服务，用于 ai_summary 和 ai_decision 步骤 */
+    aiService?: {
+        chat: (prompt: string) => Promise<string>;
+    };
+}
+export interface AgentThought {
+    step: number;
+    observation: string;
+    reasoning: string;
+    decision: string;
+    confidence: number;
+}
+export interface AgentAction {
+    type: 'tool_call' | 'delegate' | 'conclude';
+    toolName?: string;
+    toolParams?: Record<string, any>;
+    delegateTo?: string;
+    conclusion?: string;
+}
+export interface AgentState {
+    query: string;
+    context: AnalysisContext;
+    thoughts: AgentThought[];
+    toolResults: ToolResult[];
+    findings: string[];
+    currentStep: number;
+    isComplete: boolean;
+}
+export interface AnalysisContext {
+    traceId: string;
+    package?: string;
+    timeRange?: {
+        start: string;
+        end: string;
+    };
+    previousFindings?: string[];
+    userPreferences?: Record<string, any>;
+}
+export interface ExpertAgentConfig {
+    name: string;
+    domain: string;
+    description: string;
+    tools: string[];
+    maxIterations: number;
+    confidenceThreshold: number;
+}
+export interface ExpertResult {
+    agentName: string;
+    findings: Finding[];
+    diagnostics: Diagnostic[];
+    suggestions: string[];
+    confidence: number;
+    executionTimeMs: number;
+    trace: AgentTrace;
+}
+export interface Finding {
+    id: string;
+    /** 发现分类 (如: scrolling, startup, memory) */
+    category?: string;
+    /** 发现类型 (如: root_cause, performance, issue) */
+    type?: string;
+    /** 严重程度 */
+    severity: 'info' | 'warning' | 'critical' | 'low' | 'medium' | 'high';
+    title: string;
+    description: string;
+    evidence?: any[];
+    relatedTimestamps?: string[];
+    timestampsNs?: number[];
+    /** 来源 (如: decision_tree, skill, analysis) */
+    source?: string;
+    /** 置信度 (0-1) */
+    confidence?: number;
+    /** 详细信息 */
+    details?: Record<string, any>;
+    /** 优化建议 */
+    recommendations?: Array<{
+        id: string;
+        text: string;
+        priority: number;
+    }>;
+}
+export interface Diagnostic {
+    id: string;
+    condition: string;
+    matched: boolean;
+    message: string;
+    suggestions: string[];
+}
+/**
+ * Follow-up type classification for multi-turn dialogue
+ */
+export type FollowUpType = 'initial' | 'drill_down' | 'clarify' | 'extend' | 'compare';
+/**
+ * Referenced entity extracted from user query
+ * Used to link follow-up queries to previous findings
+ */
+export interface ReferencedEntity {
+    /** Entity type being referenced */
+    type: 'frame' | 'session' | 'startup' | 'process' | 'binder_call' | 'time_range';
+    /** Entity identifier (e.g., frame_id, session_id) */
+    id?: number | string;
+    /** Additional value data */
+    value?: any;
+    /** Which turn this entity was discovered in (0-based) */
+    fromTurn?: number;
+}
+export interface Intent {
+    primaryGoal: string;
+    aspects: string[];
+    expectedOutputType: 'diagnosis' | 'comparison' | 'timeline' | 'summary';
+    complexity: 'simple' | 'moderate' | 'complex';
+    /**
+     * Follow-up type for multi-turn conversations
+     * - initial: First query, no prior context
+     * - drill_down: Deep dive into specific finding (e.g., "详细分析帧456")
+     * - clarify: Request explanation of previous finding
+     * - extend: Expand analysis scope
+     * - compare: Compare multiple findings
+     */
+    followUpType?: FollowUpType;
+    /**
+     * Entities referenced in the user query that link to previous findings
+     * Populated by LLM during intent understanding
+     */
+    referencedEntities?: ReferencedEntity[];
+    /**
+     * Parameters extracted from query that can be passed directly to skills
+     * e.g., { frame_id: 456, session_id: 2 }
+     */
+    extractedParams?: Record<string, any>;
+}
+export interface AnalysisPlan {
+    tasks: AnalysisTask[];
+    estimatedDuration: number;
+    parallelizable: boolean;
+}
+export interface AnalysisTask {
+    id: string;
+    expertAgent: string;
+    objective: string;
+    dependencies: string[];
+    priority: number;
+    context: Partial<AnalysisContext>;
+}
+export interface OrchestratorResult {
+    intent: Intent;
+    plan: AnalysisPlan;
+    expertResults: ExpertResult[];
+    synthesizedAnswer: string;
+    confidence: number;
+    executionTimeMs: number;
+    trace: OrchestratorTrace;
+}
+export interface ToolCall {
+    toolName: string;
+    params: Record<string, any>;
+    result: ToolResult;
+    startTime: number;
+    endTime: number;
+}
+export interface AgentTrace {
+    agentName: string;
+    startTime: number;
+    endTime: number;
+    thoughts: AgentThought[];
+    toolCalls: ToolCall[];
+    totalTokens?: {
+        input: number;
+        output: number;
+    };
+}
+export interface OrchestratorTrace {
+    query: string;
+    intent: Intent;
+    plan: AnalysisPlan;
+    expertTraces: AgentTrace[];
+    synthesisThought: AgentThought;
+    totalDuration: number;
+    totalLLMCalls: number;
+}
+export interface ToolRegistry {
+    register(tool: Tool): void;
+    get(name: string): Tool | undefined;
+    list(): ToolDefinition[];
+    listByCategory(category: string): ToolDefinition[];
+    getToolDescriptionsForLLM(): string;
+}
+export interface AgentRegistry {
+    registerExpert(agent: ExpertAgent): void;
+    getExpert(name: string): ExpertAgent | undefined;
+    listExperts(): ExpertAgentConfig[];
+    getExpertForDomain(domain: string): ExpertAgent | undefined;
+}
+export interface ExpertAgent {
+    config: ExpertAgentConfig;
+    analyze(context: AnalysisContext): Promise<ExpertResult>;
+    canHandle(intent: Intent): boolean;
+}
+export interface OrchestratorAgent {
+    handleQuery(query: string, traceId: string, options?: OrchestratorOptions): Promise<OrchestratorResult>;
+    understandIntent(query: string): Promise<Intent>;
+    planAnalysis(intent: Intent, context: AnalysisContext): Promise<AnalysisPlan>;
+    selectExpert(task: AnalysisTask): ExpertAgent | undefined;
+    synthesize(results: ExpertResult[], intent: Intent): Promise<string>;
+}
+export interface OrchestratorOptions {
+    maxDuration?: number;
+    maxLLMCalls?: number;
+    maxExpertIterations?: number;
+    confidenceThreshold?: number;
+    streamingCallback?: (update: StreamingUpdate) => void;
+}
+export interface StreamingUpdate {
+    /**
+     * Event type for streaming updates
+     *
+     * v2.0 Events:
+     * - 'data': Unified data event carrying DataEnvelope(s)
+     *
+     * Legacy Events (backward compatibility):
+     * - 'skill_data': Skill execution results (LayeredSkillResult)
+     *
+     * Common Events:
+     * - 'thought', 'worker_thought': Agent reasoning
+     * - 'tool_call': Tool invocation
+     * - 'finding': Diagnostic finding
+     * - 'progress': Progress update
+     * - 'answer_token': Incremental final answer text stream
+     * - 'conclusion': Analysis conclusion
+     * - 'error': Error message
+     * - 'conversation_step': Strictly ordered conversational timeline event
+     *
+     * Agent-Driven Events (Phase 2-4):
+     * - 'hypothesis_generated': Initial hypotheses created
+     * - 'agent_task_dispatched': Task sent to domain agent
+     * - 'agent_dialogue': Agent communication event
+     * - 'agent_response': Agent completed task
+     * - 'round_start': Analysis round started
+     * - 'synthesis_complete': Feedback synthesis complete
+     * - 'strategy_decision': Next iteration strategy decided
+     */
+    type: 'data' | 'thought' | 'tool_call' | 'finding' | 'progress' | 'answer_token' | 'conclusion' | 'error' | 'scene_detected' | 'track_data' | 'skill_layered_result' | 'worker_thought' | 'architecture_detected' | 'conversation_step' | 'hypothesis_generated' | 'agent_task_dispatched' | 'agent_dialogue' | 'agent_response' | 'round_start' | 'synthesis_complete' | 'strategy_decision' | 'degraded' | 'stage_transition' | 'circuit_breaker' | 'intervention_required' | 'intervention_resolved' | 'intervention_timeout' | 'strategy_selected' | 'strategy_fallback' | 'sql_generated' | 'sql_validation_failed' | 'focus_updated' | 'incremental_scope' | 'sub_agent_started' | 'sub_agent_completed' | 'plan_submitted' | 'plan_phase_updated' | 'plan_revised' | 'scene_story_detected' | 'scene_story_queued' | 'scene_story_started' | 'scene_story_retrying' | 'scene_story_completed' | 'scene_story_failed' | 'scene_story_cancelled' | 'scene_story_dropped' | 'scene_story_report_ready'
+    /** @deprecated Use 'skill_layered_result' instead. Will be removed in v3.0 */
+     | 'skill_data';
+    content: any;
+    timestamp: number;
+    /**
+     * Optional unique event ID for deduplication (v2.0)
+     * Used by frontend to deduplicate events across retries/reconnects.
+     */
+    id?: string;
+}
+/**
+ * Agent execution phase enum
+ *
+ * Provides type-safe state values for the agent state machine.
+ * @see STATE_TRANSITIONS in stateMachine.ts for valid transitions
+ */
+export declare enum AgentPhase {
+    IDLE = "idle",
+    PLANNING = "planning",
+    EXECUTING = "executing",
+    EVALUATING = "evaluating",
+    REFINING = "refining",
+    AWAITING_USER = "awaiting_user",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+/**
+ * State machine event type enum
+ *
+ * Provides type-safe event names for state transitions.
+ */
+export declare enum StateEventType {
+    START_ANALYSIS = "START_ANALYSIS",
+    INTENT_UNDERSTOOD = "INTENT_UNDERSTOOD",
+    PLAN_CREATED = "PLAN_CREATED",
+    STAGE_STARTED = "STAGE_STARTED",
+    STAGE_COMPLETED = "STAGE_COMPLETED",
+    EVALUATION_COMPLETE = "EVALUATION_COMPLETE",
+    NEEDS_REFINEMENT = "NEEDS_REFINEMENT",
+    CIRCUIT_TRIPPED = "CIRCUIT_TRIPPED",
+    USER_RESPONDED = "USER_RESPONDED",
+    ANALYSIS_COMPLETE = "ANALYSIS_COMPLETE",
+    ERROR_OCCURRED = "ERROR_OCCURRED"
+}
+export interface StateEvent {
+    type: StateEventType;
+    payload?: any;
+    timestamp?: number;
+}
+export interface Checkpoint {
+    id: string;
+    stageId: string;
+    timestamp: number;
+    phase: AgentPhase;
+    agentState: SerializedAgentState;
+    stageResults: StageResult[];
+    findings: Finding[];
+    canResume: boolean;
+}
+export interface SerializedAgentState {
+    query: string;
+    traceId: string;
+    intent?: Intent;
+    plan?: AnalysisPlan;
+    expertResults: ExpertResult[];
+    iterationCount: number;
+    metadata: Record<string, any>;
+}
+export interface StateMachineConfig {
+    sessionId: string;
+    traceId: string;
+    persistPath?: string;
+    autoSave?: boolean;
+    autoSaveIntervalMs?: number;
+}
+export interface AgentStateMachineState {
+    sessionId: string;
+    traceId: string;
+    phase: AgentPhase;
+    checkpoints: Map<string, Checkpoint>;
+    iterationCounters: Map<string, number>;
+    currentStageIndex: number;
+    stageResults: Map<string, StageResult>;
+    events: StateEvent[];
+    createdAt: number;
+    updatedAt: number;
+}
+export interface PipelineStage {
+    id: string;
+    name: string;
+    description: string;
+    agentType: 'planner' | 'worker' | 'evaluator' | 'synthesizer';
+    dependencies: string[];
+    canParallelize: boolean;
+    timeout: number;
+    maxRetries: number;
+    /** 阶段元数据，用于配置额外选项如分析类型 */
+    metadata?: {
+        /** 决策树分析类型 (scrolling/launch/memory 等) */
+        analysisType?: string;
+        /** 其他自定义配置 */
+        [key: string]: any;
+    };
+}
+export interface StageResult {
+    stageId: string;
+    success: boolean;
+    data?: any;
+    error?: string;
+    findings: Finding[];
+    startTime: number;
+    endTime: number;
+    retryCount: number;
+}
+export interface PipelineConfig {
+    stages: PipelineStage[];
+    maxTotalDuration: number;
+    enableParallelization: boolean;
+    onStageComplete?: (stage: PipelineStage, result: StageResult) => void;
+    onStageError?: (stage: PipelineStage, error: Error) => PipelineErrorDecision;
+}
+export type PipelineErrorDecision = 'retry' | 'skip' | 'abort' | 'ask_user';
+export interface PipelineResult {
+    success: boolean;
+    stageResults: StageResult[];
+    totalDuration: number;
+    completedStages: string[];
+    failedStages: string[];
+    pausedAt?: string;
+    error?: string;
+}
+export interface PipelineCallbacks {
+    onStageComplete: (stage: PipelineStage, result: StageResult) => void;
+    onStageStart: (stage: PipelineStage) => void;
+    onError: (stage: PipelineStage, error: Error) => Promise<PipelineErrorDecision>;
+    onProgress: (progress: PipelineProgress) => void;
+}
+export interface PipelineProgress {
+    currentStage: string;
+    completedStages: number;
+    totalStages: number;
+    elapsedMs: number;
+    estimatedRemainingMs: number;
+}
+/**
+ * Circuit breaker state enum
+ *
+ * Provides type-safe state values for the circuit breaker pattern.
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped, requests are blocked
+ * - HALF_OPEN: Testing recovery, limited requests allowed
+ */
+export declare enum CircuitState {
+    CLOSED = "closed",
+    OPEN = "open",
+    HALF_OPEN = "half-open"
+}
+export interface CircuitBreakerConfig {
+    maxRetriesPerAgent: number;
+    maxIterationsPerStage: number;
+    cooldownMs: number;
+    halfOpenAttempts: number;
+    failureThreshold: number;
+    successThreshold: number;
+}
+export interface CircuitDecision {
+    action: 'continue' | 'retry' | 'skip' | 'abort' | 'ask_user';
+    reason?: string;
+    delay?: number;
+    context?: CircuitDiagnostics;
+}
+export interface CircuitDiagnostics {
+    agentId: string;
+    failureCount: number;
+    iterationCount: number;
+    lastError?: string;
+    lastAttemptTime: number;
+    state: CircuitState;
+    recentErrors: Array<{
+        time: number;
+        error: string;
+    }>;
+}
+export interface CircuitBreakerState {
+    state: CircuitState;
+    retryCounters: Map<string, number>;
+    iterationCounters: Map<string, number>;
+    failureHistory: Map<string, Array<{
+        time: number;
+        error: string;
+    }>>;
+    lastStateChange: number;
+    tripReason?: string;
+}
+export type ModelProvider = 'anthropic' | 'openai' | 'deepseek' | 'mock';
+export type ModelStrength = 'reasoning' | 'coding' | 'speed' | 'cost' | 'vision';
+export type TaskType = 'intent_understanding' | 'planning' | 'synthesis' | 'evaluation' | 'sql_generation' | 'code_analysis' | 'simple_extraction' | 'formatting' | 'general';
+export interface ModelProfile {
+    id: string;
+    provider: ModelProvider;
+    model: string;
+    strengths: ModelStrength[];
+    costPerInputToken: number;
+    costPerOutputToken: number;
+    avgLatencyMs: number;
+    maxTokens: number;
+    supportsJSON: boolean;
+    supportsStreaming: boolean;
+    enabled: boolean;
+}
+export interface ModelRouterConfig {
+    models: ModelProfile[];
+    defaultModel: string;
+    taskModelMapping: Partial<Record<TaskType, string>>;
+    fallbackChain: string[];
+    enableEnsemble: boolean;
+    ensembleThreshold: number;
+}
+export interface ModelCallResult {
+    modelId: string;
+    response: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalCost: number;
+    };
+    latencyMs: number;
+    success: boolean;
+    error?: string;
+}
+export interface EnsembleResult {
+    responses: ModelCallResult[];
+    aggregatedResponse: string;
+    confidence: number;
+    agreementScore: number;
+    totalCost: number;
+    totalLatencyMs: number;
+}
+export interface SubAgentConfig {
+    id: string;
+    name: string;
+    type: 'planner' | 'worker' | 'evaluator' | 'synthesizer';
+    description: string;
+    preferredModel?: TaskType;
+    tools: string[];
+    maxIterations: number;
+    confidenceThreshold: number;
+}
+export interface SubAgentContext {
+    sessionId: string;
+    traceId: string;
+    intent?: Intent;
+    plan?: AnalysisPlan;
+    previousResults?: StageResult[];
+    /** 当前迭代编号（用于去重与多轮分析） */
+    iteration?: number;
+    feedback?: EvaluationFeedback;
+    traceProcessor?: any;
+    traceProcessorService?: any;
+    /** 检测到的渲染架构信息 (Phase 1 新增) */
+    architecture?: import('../agent/detectors').ArchitectureInfo;
+    /** 用户原始查询 */
+    query?: string;
+    /** 用户查询 (别名) */
+    userQuery?: string;
+    /** 目标应用包名 */
+    package?: string;
+    /** 分析时间范围 (string for precision-safe ns timestamps) */
+    timeRange?: {
+        start: number | string;
+        end: number | string;
+    };
+    /** 分析参数（可选） */
+    analysisParams?: Record<string, any>;
+    /** AI 服务，用于 Skill 的 ai_summary 和 ai_decision 步骤 */
+    aiService?: {
+        chat: (prompt: string) => Promise<string>;
+    };
+}
+export interface SubAgentResult {
+    agentId?: string;
+    success: boolean;
+    findings: Finding[];
+    suggestions?: string[];
+    data?: any;
+    message?: string;
+    confidence?: number;
+    executionTimeMs?: number;
+    tokensUsed?: {
+        input: number;
+        output: number;
+    };
+    metrics?: Record<string, any>;
+    error?: string;
+    /** True when this turn produced a usable but incomplete result. */
+    partial?: boolean;
+    terminationReason?: string;
+    terminationMessage?: string;
+}
+export interface Evaluation {
+    passed: boolean;
+    qualityScore: number;
+    completenessScore: number;
+    contradictions: Contradiction[];
+    feedback: EvaluationFeedback;
+    needsImprovement: boolean;
+    suggestedActions: string[];
+}
+export interface Contradiction {
+    finding1: string;
+    finding2: string;
+    description: string;
+    severity: 'minor' | 'major' | 'critical';
+}
+export interface EvaluationFeedback {
+    strengths: string[];
+    weaknesses: string[];
+    missingAspects: string[];
+    improvementSuggestions: string[];
+    priorityActions: string[];
+}
+export interface EvaluationCriteria {
+    minQualityScore: number;
+    minCompletenessScore: number;
+    maxContradictions: number;
+    requiredAspects: string[];
+}
+export interface MasterOrchestratorConfig {
+    stateMachineConfig: StateMachineConfig;
+    circuitBreakerConfig: CircuitBreakerConfig;
+    modelRouterConfig: ModelRouterConfig;
+    pipelineConfig: PipelineConfig;
+    evaluationCriteria: EvaluationCriteria;
+    maxTotalIterations: number;
+    enableTraceRecording: boolean;
+    streamingCallback?: (update: StreamingUpdate) => void;
+}
+export interface MasterOrchestratorResult {
+    sessionId: string;
+    intent: Intent;
+    plan: AnalysisPlan;
+    stageResults: StageResult[];
+    evaluation: Evaluation;
+    synthesizedAnswer: string;
+    confidence: number;
+    totalDuration: number;
+    iterationCount: number;
+    modelUsage: ModelUsageSummary;
+    canResume: boolean;
+    checkpointId?: string;
+}
+export interface ModelUsageSummary {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCost: number;
+    modelBreakdown: Record<string, {
+        calls: number;
+        tokens: number;
+        cost: number;
+    }>;
+}
+export interface SessionInfo {
+    sessionId: string;
+    traceId: string;
+    query: string;
+    phase: AgentPhase;
+    createdAt: number;
+    updatedAt: number;
+    canResume: boolean;
+    lastCheckpointId?: string;
+    error?: string;
+}
+export interface RecoveryOptions {
+    fromCheckpoint?: string;
+    skipFailedStage?: boolean;
+    overrideConfig?: Partial<MasterOrchestratorConfig>;
+}
+export interface RecoveryResult {
+    success: boolean;
+    resumedFrom: string;
+    result?: MasterOrchestratorResult;
+    error?: string;
+}
+/**
+ * Represents a single conversation turn in multi-turn dialogue
+ * Used to track history and enable context-aware responses
+ */
+export interface ConversationTurn {
+    /** Unique turn identifier */
+    id: string;
+    /** Turn timestamp in milliseconds */
+    timestamp: number;
+    /** User's query for this turn */
+    query: string;
+    /** Understood intent for this query */
+    intent: Intent;
+    /** Analysis result from this turn */
+    result?: SubAgentResult;
+    /** Findings discovered in this turn */
+    findings: Finding[];
+    /** Turn index (0-based) */
+    turnIndex: number;
+    /** Whether this turn completed successfully */
+    completed: boolean;
+}
+/**
+ * Finding reference used to link between turns
+ */
+export interface FindingReference {
+    /** Finding ID to reference */
+    findingId: string;
+    /** Turn ID where finding was discovered */
+    turnId: string;
+    /** Type of reference */
+    refType: 'continuation' | 'clarification' | 'contrast' | 'expansion';
+}
+/**
+ * Context summary for LLM consumption
+ */
+export interface ContextSummary {
+    /** Total number of turns */
+    turnCount: number;
+    /** Summary of conversation so far */
+    conversationSummary: string;
+    /** Key findings from all turns */
+    keyFindings: Array<{
+        id: string;
+        title: string;
+        severity: string;
+        turnIndex: number;
+    }>;
+    /** Topics discussed */
+    topicsDiscussed: string[];
+    /** Open questions remaining */
+    openQuestions: string[];
+}
+//# sourceMappingURL=types.d.ts.map