@dataflint/mcp-server 1.0.21 → 1.0.32

package/dist/dataflint-server-models.d.ts

@@ -43,6 +43,7 @@ export interface OpportunityDetail {
     opportunity_type: string;
     expected_reduction_percentage?: number;
     description?: string;
+    impact_value?: number | null;
 }
 /**
  * Recommendation with implementation details
@@ -99,6 +100,8 @@ export interface DataFlintPromptMetadata {
 export interface DataFlintPromptsResponse {
     system_prompt: string;
     api_prompts: Array<Prompt>;
+    /** Versioning metadata — present when server supports the versioning protocol. */
+    _meta?: VersioningMeta;
 }
 /**
  * Service status information
@@ -146,7 +149,7 @@ export type FindingStatus = "active" | "dismissed" | "applied" | "stale";
  * Legacy values: simple/moderate/complex (deprecated)
  */
 export type FixComplexity = "XS" | "S" | "M" | "L" | "XL" | "simple" | "moderate" | "complex";
-export type SortBy = "opportunities" | "cost" | "latest_job_alert_count" | "duration_ms" | "idle_cores_ratio" | "start_time";
+export type SortBy = "opportunities" | "cost" | "total_cost" | "latest_job_alert_count" | "duration_ms" | "avgDuration" | "idle_cores_ratio" | "start_time" | "run_count" | "name" | "last_updated" | "last_job_status" | "team" | "domain" | "env" | "platform";
 export type TimeFilter = "all" | "quarter" | "month" | "week" | "1 day" | "6 hours" | "1 hour";
 export type HighlightSeverity = "critical" | "warning" | "info";
 export type RemapReason = "content_changed" | "user_request" | "file_renamed";
@@ -161,6 +164,7 @@ export interface CopilotApplicationRichResponse {
     team: string | null;
     domain: string | null;
     platform: string | null;
+    is_streaming?: boolean | null;
     last_updated: string;
     last_job_status: JobStatus | null;
     last_job_duration_ms: number | null;
@@ -172,6 +176,27 @@ export interface CopilotApplicationRichResponse {
     duration_opportunity: number | null;
     workflow_name: string | null;
     latest_job_id: number | null;
+    /** Trigram similarity score (0.0–1.0), present when `search` param is used */
+    match_score?: number | null;
+    /** Server-constructed canonical URL to the latest run in the web dashboard */
+    dashboard_url?: string | null;
+}
+/**
+ * Metadata about the date range and pagination of retrieved data
+ */
+export interface DateRangeMetadata {
+    time_period: string;
+    from_date: string;
+    to_date: string;
+    total_count: number;
+    returned_count: number;
+}
+/**
+ * Wrapper response for applications with date range metadata
+ */
+export interface CopilotApplicationsResponse {
+    data_range: DateRangeMetadata;
+    applications: CopilotApplicationRichResponse[];
 }
 /**
  * Rich job response with comprehensive metadata
@@ -183,8 +208,8 @@ export interface CopilotJobRichResponse {
     start_time: string;
     end_time: string;
     duration_ms: number;
-    history_server_url: string;
-    env: string;
+    history_server_url: string | null;
+    env: string | null;
     team: string | null;
     domain: string | null;
     platform: string | null;
@@ -195,12 +220,12 @@ export interface CopilotJobRichResponse {
     cost_unit: string;
     infrastructure_cost: number | null;
     compute_cost: number | null;
-    idle_cores_ratio: number;
-    task_error_rate: number;
-    container_memory_gb: number;
-    executor_peak_memory_bytes: number;
-    core_hour_usage: number;
-    memory_gb_hour: number;
+    idle_cores_ratio: number | null;
+    task_error_rate: number | null;
+    container_memory_gb: number | null;
+    executor_peak_memory_bytes: number | null;
+    core_hour_usage: number | null;
+    memory_gb_hour: number | null;
     total_input_bytes: number;
     total_output_bytes: number;
     total_shuffle_read_bytes: number;
@@ -210,12 +235,19 @@ export interface CopilotJobRichResponse {
     duration_opportunity: number | null;
     workflow_run_id: string | null;
     workflow_name: string | null;
+    application_id: number | null;
+    application_name: string | null;
+    /** Cluster configuration (platform_details stripped in list endpoints) */
+    cluster?: CopilotClusterInfo | null;
+    /** Server-constructed canonical URL to this job in the web dashboard */
+    dashboard_url?: string | null;
 }
 /**
  * Query parameters for get_applications
  */
 export interface GetApplicationsParams {
     search?: string;
+    env?: string;
     team?: string;
     domain?: string;
     platform?: "databricks" | "emr";
@@ -225,10 +257,11 @@ export interface GetApplicationsParams {
     limit?: number;
 }
 /**
- * Query parameters for get_jobs_rich
+ * Query parameters for get_application_jobs (unified endpoint)
  */
-export interface GetJobsRichParams {
+export interface GetApplicationJobsParams {
     application_id: number;
+    detail?: "full" | "minimal";
     time?: TimeFilter;
     limit?: number;
 }
@@ -261,8 +294,9 @@ export interface NodeContribution {
     sqlId: number;
     nodeId: number;
     nodeName: string;
-    durationPct: number;
-    metricsLine: string;
+    durationPctOfQuery: number;
+    durationPctOfJob: number;
+    metricsLine: string | null;
     code: string;
     queryStatus?: string;
     queryDescription?: string;
@@ -294,8 +328,26 @@ export interface AggregatedHighlight {
     hasFix?: boolean;
     /** Number of additional items beyond the top one */
     additionalCount?: number;
+    isActionTrigger?: boolean;
+    actionInfo?: {
+        actionSyntax?: string;
+        durationMs: number;
+        resourceDurationMs: number;
+        durationFormatted: string;
+        resourceDurationFormatted: string;
+        stageCount: number;
+        metricsLine: string;
+    };
     combinedMetrics: string;
     contributions: NodeContribution[];
+    alerts?: Array<{
+        name: string;
+        title: string;
+        message: string;
+        severity: string;
+        suggestions?: string;
+        nodeIds?: number[];
+    }>;
 }
 /**
  * Response from highlight endpoints
@@ -312,15 +364,134 @@ export interface HighlightResponse {
      */
     history_server_url?: string;
 }
+/**
+ * Pinpoints issue in source code.
+ * Maps to SHS /dataflint/code/combined endpoint.
+ *
+ * Privacy: The `code_snippet` field is controlled by privacy.sendSourceCode
+ * setting (default: false). When enabled, code is automatically obfuscated
+ * (variables→v1, strings→"str_1") before transmission. If obfuscation is
+ * unavailable, code is NOT sent (privacy-first).
+ */
+export interface CodeLocation {
+    /** Source file path (e.g., "etl.py") - always sent */
+    file: string;
+    /** Line number in source file (1-indexed) - always sent */
+    line: number;
+    /** Index in code/combined mapping (for ?map= parameter) - always sent */
+    mapping_index?: number;
+    /** The actual code line or snippet - PRIVACY CONTROLLED: obfuscated or stripped */
+    code_snippet?: string;
+}
+/**
+ * Pinpoints issue in Spark execution plan.
+ * Maps to SHS /dataflint/plan/enriched/json endpoint.
+ */
+export interface PlanLocation {
+    /** Human-readable operator name (e.g., "Read parquet") */
+    node_name: string;
+    /** Spark operator class (e.g., "FileSourceScanExec") */
+    operator_type?: string;
+    /** Spark stage ID (-1 for pre-shuffle cluster) */
+    stage_id?: number;
+    /** Parent nodes in the execution DAG */
+    parent_node_ids?: number[];
+}
+/**
+ * Version and context for reproducibility.
+ * Helps track which version of analysis data was used.
+ */
+export interface DataContext {
+    /** Codegen version string from SHS */
+    codegen_version?: string;
+    /** When the LLM analysis was performed (ISO 8601) */
+    analysis_timestamp?: string;
+}
+/**
+ * Legacy: Structured evidence supporting the finding.
+ * @deprecated Use evidence[] and reasoning_steps[] instead
+ */
+export interface ReasoningEvidence {
+    /** Key metrics (e.g., { duration_pct: 45.5, rows: "1.2M" }) */
+    metrics_observed?: Record<string, unknown>;
+    /** Pattern identifier (e.g., "sequential_read_anti_pattern") */
+    pattern_detected?: string;
+    /** Factors contributing to confidence score */
+    confidence_factors?: string[];
+}
+/**
+ * Evidence entry - metrics examined with source path and actual value
+ */
+export interface EvidenceEntry {
+    /** Evidence type (e.g., "Partition count", "SerDe overhead") */
+    type: string;
+    /** Path in plan data (e.g., "executions[3].stages[12].timeBreakdown.serDeser") */
+    source: string;
+    /** Actual value observed (e.g., "53.2%", "10000 partitions") */
+    value: string;
+}
+/**
+ * Missing data entry - what would have helped the analysis
+ */
+export interface MissingDataEntry {
+    /** What data was missing */
+    data: string;
+    /** Why it would help */
+    reason: string;
+    /** Impact level */
+    impact: "low" | "medium" | "high";
+}
+/**
+ * Source location for code pinpointing
+ */
+export interface SourceLocation {
+    /** Source file path (e.g., "etl.py") */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Code snippet - PRIVACY CONTROLLED */
+    snippet?: string;
+    /** Index in code/combined mapping */
+    mapping_index?: number;
+}
+/**
+ * Fix option with complexity and impact
+ */
+export interface FixOption {
+    /** What to do (e.g., "Reduce partitions to 50") */
+    description: string;
+    /** Implementation effort */
+    complexity: "XS" | "S" | "M" | "L" | "XL";
+    /** Expected improvement (e.g., "3 min faster") */
+    impact: string;
+    /** Example code - PRIVACY CONTROLLED */
+    code_example?: string;
+}
+/**
+ * Related node with relationship type
+ */
+export interface RelatedNode {
+    /** SQL query ID */
+    sql_id: number;
+    /** Node ID */
+    node_id: number;
+    /** Relationship type */
+    relationship: "causes" | "executes" | "reads_from" | "writes_to" | "depends_on";
+}
+/**
+ * Downstream impact entry
+ */
+export interface DownstreamImpact {
+    /** Affected SQL query ID */
+    sql_id: number;
+    /** How it's affected */
+    impact: string;
+}
 /**
  * LLM-identified finding for submission
  *
- * Aligned with SHS Alert structure:
- * - title: Short display (like Alert.title)
- * - message: Detailed explanation (like Alert.message)
- * - type/severity: critical/warning/hint/insight/context
- * - suggestion: What to do (like Alert.suggestions)
- * - fix_complexity: XS/S/M/L/XL (like Alert.easeOfImplementation)
+ * Rich evidence structure aligned with Analysis Reports.
+ * Server enriches with SHS visualization URLs.
  */
 export interface LLMFinding {
     node_id: number;
@@ -328,11 +499,33 @@ export interface LLMFinding {
     title: string;
     message?: string;
     confidence: number;
+    /** Evidence examined: metrics with paths and actual values */
+    evidence?: EvidenceEntry[];
+    /** Reasoning steps: calculations, threshold comparisons */
+    reasoning_steps?: string[];
+    /** What data would have helped the analysis */
+    missing_data?: MissingDataEntry[];
+    /** Source code locations (array for multi-location findings) */
+    source_locations?: SourceLocation[];
+    /** Spark plan pinpointing */
+    plan_location?: PlanLocation;
+    /** Multiple fix options with complexity and impact */
+    fix_options?: FixOption[];
     suggestion?: string;
     code_snippet?: string;
     fix_complexity?: FixComplexity;
     estimated_impact?: string;
+    /** Related nodes with relationship type */
+    related_nodes?: RelatedNode[];
+    /** Downstream queries impacted */
+    downstream_impact?: DownstreamImpact[];
     related_node_ids?: number[];
+    /** @deprecated Use source_locations[] instead */
+    code_location?: CodeLocation;
+    /** @deprecated */
+    data_context?: DataContext;
+    /** @deprecated Use evidence[] and reasoning_steps[] instead */
+    reasoning?: ReasoningEvidence;
 }
 /**
  * Request body for submit_highlight_findings
@@ -357,6 +550,8 @@ export interface FindingsResponse {
     stored_count: number;
     skipped_count: number;
     updated_metrics: UpdatedMetric[];
+    /** Server-assigned IDs for persisted findings. Used to link findings to analysis reports. */
+    finding_ids?: number[];
 }
 /**
  * Response from clear_highlights
@@ -475,17 +670,19 @@ export interface MultiNodeFindingsResponse {
  * Spark expertise document section
  */
 export interface ExpertiseDocSection {
-    title: string;
-    content: string;
+    file: string;
+    section: string;
 }
 /**
  * Response from get_spark_expertise
  */
 export interface SparkExpertiseResponse {
     topic: string;
+    title: string;
     quick_advice: string;
     trigger_patterns: string[];
     doc_sections?: ExpertiseDocSection[];
+    doc_content?: string | null;
 }
 /**
  * Individual expertise topic info
@@ -503,7 +700,7 @@ export interface ExpertiseTopicsResponse {
 /**
  * Available prompt layers
  */
-export type PromptLayerType = "core" | "analysis" | "highlight" | "optimize" | "app_analysis";
+export type PromptLayerType = "core" | "analysis" | "streaming" | "highlight" | "highlight_streaming" | "optimize" | "app_analysis";
 /**
  * Response from get_prompt_layer
  */
@@ -591,6 +788,75 @@ export type IssueType = "incorrect_data" | "misplaced" | "both" | "other";
  * Issue severity level
  */
 export type IssueSeverity = "low" | "medium" | "high" | "critical";
+/**
+ * Level at which issue is reported
+ */
+export type IssueLevel = "job" | "application" | "workflow_run";
+/**
+ * Job and workflow context for issue reports
+ */
+export interface IssueReportJobContext {
+    run_id?: string;
+    spark_app_id?: string;
+    application_id?: number;
+    application_name?: string;
+    workflow_run_id?: string;
+    workflow_name?: string;
+    platform?: string;
+    env?: string;
+    team?: string;
+    domain?: string;
+    history_server_url?: string;
+    customer_id?: string;
+}
+/**
+ * Code location for pinpointing (aligned with LLM Findings)
+ */
+export interface IssueReportCodeLocation {
+    file: string;
+    line: number;
+    /** Index in code/combined mapping (for SHS ?map= parameter) */
+    mapping_index?: number;
+    /** Obfuscated code snippet */
+    code_snippet?: string;
+}
+/**
+ * Plan location for pinpointing (aligned with LLM Findings)
+ */
+export interface IssueReportPlanLocation {
+    /** Human-readable operator name (e.g., 'Read parquet', 'HashAggregate') */
+    node_name?: string;
+    /** Spark operator class (e.g., 'FileSourceScanExec') */
+    operator_type?: string;
+    /** Spark stage ID */
+    stage_id?: number;
+    /** Parent nodes in the execution DAG */
+    parent_node_ids?: number[];
+}
+/**
+ * Data context for version tracking (aligned with LLM Findings)
+ */
+export interface IssueReportDataContext {
+    /** Codegen version from SHS */
+    codegen_version?: string;
+    /** Hash of code/mapping data for tracking file state changes */
+    mapping_hash?: string;
+    /** When the analysis was performed (ISO 8601) */
+    analysis_timestamp?: string;
+    /** Path to .data.json.gz file */
+    data_file?: string;
+}
+/**
+ * Highlight contribution for multi-operation highlights
+ */
+export interface IssueReportHighlightContribution {
+    sql_id: number;
+    node_id: number;
+    node_name?: string;
+    duration_pct?: number;
+    metrics_line?: string;
+    query_prefix?: string;
+}
 /**
  * Issue type option from server metadata
  */
@@ -619,11 +885,20 @@ export interface DataSharingOption {
     default_checked?: boolean;
 }
 /**
- * Response from GET /api/copilot/issue-report/metadata
+ * Issue level option from server metadata
+ */
+export interface IssueLevelOption {
+    value: IssueLevel;
+    label: string;
+    description: string;
+}
+/**
+ * Response from GET /api/copilot/extension/issue-report/metadata
  */
 export interface IssueReportMetadataResponse {
     issue_types: IssueTypeOption[];
     severity_levels: SeverityLevelOption[];
+    issue_levels?: IssueLevelOption[];
     privacy_notice: string;
     data_sharing_options: DataSharingOption[];
 }
@@ -655,11 +930,27 @@ export interface IssueReportHighlightContext {
     is_hotspot: boolean;
     severity?: string;
     query_prefix?: string;
+    /** Deep link URL path (e.g., "/graph/?sqlid=2&nodeids=8,10") */
+    deep_link_url?: string;
+    /** Individual contributions for multi-operation highlights */
+    contributions?: IssueReportHighlightContribution[];
+    /** Alert count for context */
+    alert_count?: number;
+    /** Finding count for context */
+    finding_count?: number;
 }
 /**
- * Request body for POST /api/copilot/highlights/{job_id}/report-issue
+ * Request body for POST /api/copilot/extension/highlights/{job_id}/report-issue
  */
 export interface IssueReportRequest {
+    /** Level at which issue is reported (defaults to "job") */
+    issue_level?: IssueLevel;
+    /** Job ID (for job-level issues, injected from path param) */
+    job_id?: number;
+    /** Application ID (for application-level issues) */
+    application_id?: number;
+    /** Workflow run ID (for workflow-level issues) */
+    workflow_run_id?: number;
     issue_type: IssueType;
     highlight: IssueReportHighlightContext;
     severity?: IssueSeverity;
@@ -670,11 +961,21 @@ export interface IssueReportRequest {
     obfuscated_code?: ObfuscatedCodeContext;
     /** Reason why code was not included (if user opted in but obfuscation failed) */
     code_omission_reason?: string;
+    /** Job, application, and workflow context metadata */
+    job_context?: IssueReportJobContext;
+    /** Source code pinpointing (file, line, mapping index for SHS ?map= param) */
+    code_location?: IssueReportCodeLocation;
+    /** Spark plan pinpointing (node name, operator type, stage) */
+    plan_location?: IssueReportPlanLocation;
+    /** Analysis version context for reproducibility */
+    data_context?: IssueReportDataContext;
     extension_version?: string;
     editor_type?: "vscode" | "cursor";
+    /** LLM model used during session (also sent via X-DF-LLM-MODEL header) */
+    llm_model?: string;
 }
 /**
- * Response from POST /api/copilot/highlights/{job_id}/report-issue
+ * Response from POST /api/copilot/extension/highlights/{job_id}/report-issue
  */
 export interface IssueReportResponse {
     report_id: string;
@@ -682,4 +983,425 @@ export interface IssueReportResponse {
     message: string;
     created_at: string;
 }
+/**
+ * Platform-agnostic cluster representation for LLM analysis.
+ * Common fields are normalized across Databricks, EMR, and Dataproc.
+ * `platform_details` is stripped in list endpoints to save tokens.
+ */
+export interface CopilotClusterInfo {
+    cluster_id: string;
+    platform: string;
+    worker_instance_type: string | null;
+    driver_instance_type: string | null;
+    num_workers: number | null;
+    autoscaling_enabled: boolean;
+    min_workers: number | null;
+    max_workers: number | null;
+    spot_enabled: boolean | null;
+    spot_bid_percent: number | null;
+    runtime_version: string | null;
+    cluster_url: string | null;
+    total_cost_usd: number | null;
+    infrastructure_cost_usd: number | null;
+    compute_cost_usd: number | null;
+    platform_details: Record<string, unknown> | null;
+}
+export type WorkflowSortBy = "cost" | "opportunities" | "dag_runs_count" | "avg_execution_duration" | "last_updated_job_execution" | "workflow_name" | "dag_id" | "status" | "team" | "domain" | "env" | "platform";
+export type WorkflowRunSortBy = "started_at" | "cost" | "cost_percentile" | "opportunities" | "duration_ms" | "status" | "total_input_bytes" | "total_output_bytes";
+export type WorkflowPlatform = "databricks" | "emr" | "eks";
+/**
+ * Rich workflow response with health and performance indicators.
+ * Returned by GET /api/copilot/workflows
+ */
+export interface CopilotWorkflowResponse {
+    id: number;
+    name: string | null;
+    workflow_id: string;
+    env: string | null;
+    team: string | null;
+    domain: string | null;
+    platform: string | null;
+    orchestrator_type: string | null;
+    total_steps: number | null;
+    is_active: boolean;
+    last_run_status: string | null;
+    last_run_at: string | null;
+    run_count: number;
+    avg_duration_ms: number | null;
+    total_cost_usd: number | null;
+    avg_cost_usd: number | null;
+    total_opportunity_dollars: number | null;
+    success_rate: number | null;
+    avg_alert_count: number | null;
+    /** Trigram similarity score (0.0–1.0), present when `search` param is used */
+    match_score?: number | null;
+}
+/**
+ * Minimal workflow run response (~100 tokens per run).
+ * Returned by GET /api/copilot/workflow/runs?detail=minimal
+ */
+export interface CopilotWorkflowRunMinimalResponse {
+    id: number;
+    dag_run_id: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    duration_ms: number | null;
+    status: string;
+    workflow_id: number | null;
+    workflow_name: string | null;
+}
+/**
+ * Rich workflow run response for LLM analysis (~300 tokens per run).
+ * Returned by GET /api/copilot/workflow/runs?detail=full
+ */
+export interface CopilotWorkflowRunRichResponse extends CopilotWorkflowRunMinimalResponse {
+    run_name: string | null;
+    total_steps: number | null;
+    completed_steps: number | null;
+    failed_steps: number | null;
+    completion_percentage: number | null;
+    total_cost_usd: number | null;
+    total_infrastructure_cost: number | null;
+    total_compute_cost: number | null;
+    total_opportunity_dollars: number | null;
+    alert_count: number | null;
+    error_message: string | null;
+    trigger_type: string | null;
+    /** Cluster details (one per unique cluster used in this run, platform_details stripped) */
+    clusters?: CopilotClusterInfo[];
+}
+/**
+ * A Spark job within a workflow run, bridging workflow context to job-level analysis.
+ * Returned by GET /api/copilot/workflow/run/jobs
+ */
+export interface CopilotWorkflowRunJobResponse {
+    step_name: string | null;
+    step_order: number | null;
+    job_id: number | null;
+    application_id: number | null;
+    application_name: string | null;
+    run_id: string | null;
+    history_server_url: string | null;
+    start_time: string | null;
+    end_time: string | null;
+    duration_ms: number | null;
+    status: string | null;
+    cost_usd: number | null;
+    cost_opportunity_dollars: number | null;
+    alert_count: number;
+    idle_cores_ratio: number | null;
+    total_spill_bytes: number | null;
+    total_input_bytes: number | null;
+    total_output_bytes: number | null;
+    /** Cluster configuration (platform_details stripped) */
+    cluster?: CopilotClusterInfo | null;
+    /** Server-constructed canonical URL to this job run in the web dashboard */
+    dashboard_url?: string | null;
+}
+/**
+ * Query parameters for get_workflows
+ */
+export interface GetWorkflowsParams {
+    search?: string;
+    team?: string;
+    domain?: string;
+    platform?: WorkflowPlatform;
+    time?: TimeFilter;
+    sort_by?: WorkflowSortBy;
+    sort_direction?: "desc" | "asc";
+    limit?: number;
+}
+/**
+ * Query parameters for get_workflow_runs
+ */
+export interface GetWorkflowRunsParams {
+    workflow_id: number;
+    detail?: "full" | "minimal";
+    time?: TimeFilter;
+    limit?: number;
+    sort_by?: WorkflowRunSortBy;
+    sort_direction?: "desc" | "asc";
+}
+/**
+ * Query parameters for get_workflow_run_jobs
+ */
+export interface GetWorkflowRunJobsParams {
+    workflow_id: number;
+    workflow_run_id: number;
+}
+/**
+ * Trigger type for analysis report
+ */
+export type AnalysisReportTriggerType = "explain" | "fix" | "analyze" | "optimize" | "highlight" | "ask";
+/**
+ * Evidence entry from LLM analysis
+ */
+export interface AnalysisReportEvidenceEntry {
+    type: string;
+    source: string;
+    value: string;
+}
+/**
+ * Missing data entry from LLM analysis
+ */
+export interface AnalysisReportMissingEntry {
+    data: string;
+    reason: string;
+    impact: "low" | "medium" | "high";
+}
+/**
+ * Finding from LLM analysis report
+ */
+export interface AnalysisReportFinding {
+    number: number;
+    title: string;
+    evidence: AnalysisReportEvidenceEntry[];
+    reasoning: string[];
+    missing: AnalysisReportMissingEntry[];
+    actions: string[];
+}
+/**
+ * Context for what triggered the analysis
+ */
+export interface AnalysisReportTriggerContext {
+    sql_id?: number;
+    node_id?: number;
+    alert_type?: string;
+}
+/**
+ * Summary statistics of the report
+ */
+export interface AnalysisReportSummary {
+    findings_count: number;
+    evidence_count: number;
+    missing_count: number;
+    parse_errors: string[];
+}
+/**
+ * Examined node entry - what was checked during analysis
+ */
+export interface ExaminedNodeEntry {
+    sql_id: number;
+    node_id: number;
+    what_checked: string;
+}
+/**
+ * No-issue explanation - why a node was NOT flagged
+ */
+export interface NoIssueExplanationEntry {
+    sql_id: number;
+    node_id: number;
+    observation: string;
+    why_ok: string;
+}
+/**
+ * Cross-finding pattern - relationships between findings
+ */
+export interface CrossFindingPatternEntry {
+    finding_indices: number[];
+    pattern: string;
+}
+/**
+ * Request body for POST /api/copilot/platform/analysis-report
+ *
+ * IMPORTANT: Reports reference findings by ID, NOT by copying data.
+ * Findings must be POSTed first to /findings, then IDs are included here.
+ *
+ * Report contains session-level analysis only:
+ * - finding_ids (references to persisted findings)
+ * - examined_nodes (what was checked)
+ * - no_issue_explanations (why nodes were NOT flagged)
+ * - overall_assessment (job-level summary)
+ * - analysis_approach (what strategy was used)
+ */
+export interface AnalysisReportPayload {
+    job_id: number;
+    trigger_type: AnalysisReportTriggerType;
+    trigger_context?: AnalysisReportTriggerContext | null;
+    finding_ids?: number[];
+    examined_nodes?: ExaminedNodeEntry[];
+    no_issue_explanations?: NoIssueExplanationEntry[];
+    overall_assessment?: string;
+    analysis_approach?: string;
+    cross_finding_patterns?: CrossFindingPatternEntry[];
+    /** LLM model used during session (also sent via X-DF-LLM-MODEL header) */
+    llm_model?: string;
+    report?: AnalysisReportSummary;
+    parse_errors?: string[];
+    timestamp?: string | null;
+    /** Extension-side discovery audit trail (zero LLM involvement) */
+    discovery_context?: DiscoveryContext;
+}
+/**
+ * Extension-side discovery context tracking.
+ *
+ * Captures what the server cannot see:
+ * - Whether a workspace context hint was injected
+ * - Which fast path the session took
+ * - The full sequence of discovery API calls with timing
+ *
+ * All collected with zero LLM involvement.
+ */
+/**
+ * Workspace hint from the scanner, included in discovery context.
+ */
+export interface DiscoveryWorkspaceHint {
+    app_hint: string | null;
+    matched_app_id: number | null;
+    matched_job_id: number | null;
+    confidence: "PRE_MATCHED" | "HIGH" | "MEDIUM" | "LOW" | "NONE";
+    source: string;
+}
+export interface DiscoveryContext {
+    /** Workspace context from scanner (see WORKSPACE_CONTEXT_DETECTION.md) */
+    workspace_hint?: DiscoveryWorkspaceHint;
+    /** Which discovery fast path was used */
+    fast_path_used: "workspace_context" | "latest_job_id" | "intent_job_id" | "standard";
+    /** Chronological record of discovery API calls */
+    discovery_calls: DiscoveryCall[];
+}
+/**
+ * A single discovery API call record.
+ */
+export interface DiscoveryCall {
+    tool: "get_applications" | "get_application_jobs";
+    params: Record<string, unknown>;
+    result_count: number;
+    timestamp: string;
+}
+/**
+ * Response from POST /api/copilot/platform/analysis-report
+ *
+ * Server uses smart upsert - repeated submissions for same session+job
+ * are merged intelligently with audit trail.
+ */
+export interface AnalysisReportResponse {
+    id: number;
+    report_id?: number;
+    status: string;
+    was_merged?: boolean;
+    submission_count?: number;
+    findings_count?: number;
+    examined_count?: number;
+    no_issues_count?: number;
+    evidence_count?: number;
+    missing_count?: number;
+}
+/**
+ * A single copilot activity event.
+ *
+ * Tracks user interactions with the extension to understand
+ * adoption, feature usage, and onboarding progression.
+ */
+export interface CopilotActivityEvent {
+    /** Event category: milestone reached, nudge shown/dismissed, feature used */
+    event_type: "session_start" | "milestone_reached" | "interaction" | "nudge_shown" | "nudge_dismissed" | "walkthrough_opened" | "consent";
+    /** Specific event identifier (e.g. milestone key, nudge ID) */
+    event_name: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Additional event-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request body for POST /api/copilot/extension/activity
+ */
+export interface CopilotActivityPayload {
+    /** Batch of activity events */
+    events: CopilotActivityEvent[];
+    /** Current session number (how many times the extension has activated) */
+    session_count: number;
+    /** Snapshot of reached milestones at time of submission */
+    milestones: Record<string, boolean>;
+    /** Extension version */
+    extension_version?: string;
+    /** IDE type (vscode, cursor) */
+    ide_type?: string;
+}
+/**
+ * Response from POST /api/copilot/extension/activity
+ */
+export interface CopilotActivityResponse {
+    status: string;
+    events_received: number;
+}
+/**
+ * Versioning metadata optionally returned by any server-managed config/prompt
+ * endpoint. All fields are optional so older servers that predate this
+ * protocol still produce a valid response.
+ */
+export interface VersioningMeta {
+    /** Server-side contract version for this payload (integer, monotonically increasing). */
+    contract_version?: number;
+    /** Minimum extension version required to consume this payload correctly (semver). */
+    min_extension_version?: string;
+    /** Human-readable deprecation notice for the current extension version. */
+    deprecation_notice?: string;
+}
+/**
+ * Server-managed tuning parameters for client behaviour.
+ *
+ * The server returns these inside `GET /api/copilot/extension/config` so that
+ * retry budgets, polling intervals, and compression can be adjusted
+ * without shipping a new extension version.
+ *
+ * Every field is optional — the extension falls back to built-in defaults
+ * when a field is absent.
+ */
+export interface ClientTuningConfig {
+    /** Retry settings for transient-failure endpoints (job/plan, job/code). */
+    retry?: {
+        /** Max retry attempts (default: 25). */
+        retries?: number;
+        /** Exponential backoff multiplier (default: 2). */
+        factor?: number;
+        /** Initial retry delay in ms (default: 200). */
+        min_timeout_ms?: number;
+        /** Max retry delay cap in ms (default: 5000). */
+        max_timeout_ms?: number;
+        /** Add jitter to prevent thundering herd (default: true). */
+        randomize?: boolean;
+    };
+    /** Request-level timeout in ms (default: 30 000). */
+    request_timeout_ms?: number;
+    /** Activity reporter flush interval in ms (default: 60 000). */
+    activity_flush_interval_ms?: number;
+    /** Background workspace sync interval in ms (default: 300 000). */
+    background_sync_interval_ms?: number;
+    /** Mapping panel background refresh interval in ms (default: 300 000). */
+    mapping_refresh_interval_ms?: number;
+    /** Mapping panel staleness threshold in ms (default: 120 000). */
+    mapping_stale_threshold_ms?: number;
+}
+/**
+ * Response from GET /api/copilot/extension/prompt-templates
+ * Contains server-managed LLM instructional text (roles, tools, quick start)
+ * that the extension injects into AI sessions via placeholder substitution.
+ */
+export interface PromptTemplatesResponse {
+    version: string;
+    expert_sessions: {
+        roles: Record<string, string>;
+        analysis_levels: Record<string, string>;
+        critical_first_step: string;
+        tools_available: Record<string, string>;
+        quick_start: Record<string, {
+            job_level: string;
+            app_level: string;
+        }>;
+    };
+    _meta?: VersioningMeta;
+}
+/**
+ * Response from GET /api/copilot/extension/config
+ * Contains server-managed URL templates for all extension CTAs.
+ */
+export interface CopilotConfigResponse {
+    version: string;
+    urls: Record<string, string>;
+    /** Server-managed tuning for client behaviour (retry, intervals, compression). */
+    client_tuning?: ClientTuningConfig;
+    /** Versioning metadata — present when server supports the versioning protocol. */
+    _meta?: VersioningMeta;
+}
 //# sourceMappingURL=dataflint-server-models.d.ts.map