@scanwarp/core 0.2.0 → 0.3.0

package/dist/diagnoser.d.ts

@@ -1,8 +1,14 @@
-import type { Event, Monitor, DiagnosisResult } from './types.js';
+import type { Event, Monitor, DiagnosisResult, TraceSpan } from './types.js';
 interface DiagnoserConfig {
     apiKey: string;
     model?: string;
 }
+interface ProviderStatusContext {
+    provider: string;
+    displayName: string;
+    status: string;
+    description: string | null;
+}
 interface DiagnosisContext {
     events: Event[];
     monitor?: Monitor;
@@ -11,7 +17,10 @@ interface DiagnosisContext {
         status: string;
         message: string;
     }>;
+    traces?: TraceSpan[];
+    providerStatuses?: ProviderStatusContext[];
 }
+export { type DiagnosisContext };
 export declare class Diagnoser {
     private client;
     private model;
@@ -23,4 +32,3 @@ export declare class Diagnoser {
     private parseResponse;
     private normalizeSeverity;
 }
-export {};

package/dist/diagnoser.js

@@ -20,7 +20,7 @@ class Diagnoser {
             model: this.model,
             max_tokens: 2000,
             temperature: 0.3,
-            system: this.getSystemPrompt(),
+            system: this.getSystemPrompt(context),
             messages: [
                 {
                     role: 'user',
@@ -34,43 +34,69 @@ class Diagnoser {
         }
         return this.parseResponse(content.text);
     }
-    getSystemPrompt() {
-        return `You are a senior engineering mentor helping developers who built their application using AI coding tools like Cursor or Claude Code. These developers may not have deep infrastructure knowledge or be familiar with reading stack traces.
-
-Your job is to:
-1. Explain what went wrong in plain, conversational English (no jargon)
-2. Explain WHY it happened in a way a non-expert can understand
-3. Provide a clear, actionable fix in plain language
-4. Write a ready-to-paste prompt they can give to their AI coding assistant to fix the issue
-
-Think of yourself as a patient mentor who's explaining a production issue to someone smart but new to production systems.
-
-IMPORTANT RULES:
-- NO technical jargon without explanation
-- NO raw stack traces in your response
-- Use analogies when helpful
-- Be encouraging, not condescending
-- Focus on "what to do" not "what you did wrong"
-
-Respond in this exact JSON format:
-{
-  "root_cause": "1-2 sentence plain English explanation of what broke",
-  "severity": "critical|warning|info",
-  "suggested_fix": "Plain English explanation of how to fix it (2-4 sentences)",
-  "fix_prompt": "A complete, copy-pasteable prompt for Cursor/Claude Code that will fix this issue"
-}
-
-The fix_prompt should be detailed and include:
-- What file(s) to modify
-- What specific changes to make
-- Any environment variables or config needed
-- How to test the fix
-
+    getSystemPrompt(context) {
+        const hasTraces = context.traces && context.traces.length > 0;
+        const hasProviderIssues = context.providerStatuses && context.providerStatuses.length > 0;
+        let prompt = `You are a senior engineering mentor helping developers who built their application using AI coding tools like Cursor or Claude Code. These developers may not have deep infrastructure knowledge or be familiar with reading stack traces.
+
+Your job is to:
+1. Explain what went wrong in plain, conversational English (no jargon)
+2. Explain WHY it happened in a way a non-expert can understand
+3. Provide a clear, actionable fix in plain language
+4. Write a ready-to-paste prompt they can give to their AI coding assistant to fix the issue${hasTraces ? '\n5. Identify the specific span (operation) that is the bottleneck or root cause' : ''}
+
+Think of yourself as a patient mentor who's explaining a production issue to someone smart but new to production systems.
+
+IMPORTANT RULES:
+- NO technical jargon without explanation
+- NO raw stack traces in your response
+- Use analogies when helpful
+- Be encouraging, not condescending
+- Focus on "what to do" not "what you did wrong"${hasTraces ? '\n- When trace data is available, use it to pinpoint the EXACT operation that failed or is slow' : ''}`;
+        if (hasProviderIssues) {
+            prompt += `
+
+PROVIDER OUTAGE RULES (CRITICAL — follow these when provider status data shows a non-operational provider):
+- If the issue correlates with a provider that is currently experiencing an outage or degraded performance, clearly state that the issue is CAUSED BY the provider outage, NOT a bug in the user's code
+- The root_cause MUST mention the provider by name and their current status (e.g. "This is caused by a Vercel outage, not a bug in your code")
+- The suggested_fix should focus on: (1) waiting for the provider to recover, (2) checking the provider's status page, and (3) any temporary workarounds
+- Do NOT suggest code fixes for issues caused by provider outages — it's not the user's fault
+- The fix_prompt should suggest adding resilience improvements (retry logic, fallbacks, circuit breakers) as an OPTIONAL improvement, not as a bug fix`;
+        }
+        prompt += `
+
+Respond in this exact JSON format:
+{
+  "root_cause": "1-2 sentence plain English explanation of what broke",
+  "severity": "critical|warning|info",
+  "suggested_fix": "Plain English explanation of how to fix it (2-4 sentences)",
+  "fix_prompt": "A complete, copy-pasteable prompt for Cursor/Claude Code that will fix this issue"${hasTraces ? `,
+  "bottleneck_span": "name of the span that is the root cause (e.g. 'stripe: payment_intents.create' or 'pg: SELECT * FROM users')",
+  "trace_id": "the trace_id of the most relevant trace"` : ''}
+}
+
+The fix_prompt should be detailed and include:
+- What file(s) to modify
+- What specific changes to make
+- Any environment variables or config needed
+- How to test the fix
+
 Make the fix_prompt actionable enough that an AI coding assistant can implement it without asking follow-up questions.`;
+        return prompt;
     }
     buildPrompt(context) {
-        const { events, monitor, recentHistory } = context;
+        const { events, monitor, recentHistory, traces, providerStatuses } = context;
         let prompt = '## Production Issue Detected\n\n';
+        // Provider status section — show this first so the AI sees it immediately
+        if (providerStatuses && providerStatuses.length > 0) {
+            prompt += '**⚠️ Provider Status (current):**\n';
+            for (const ps of providerStatuses) {
+                const statusLabel = ps.status === 'operational' ? '✅ operational' : `🔴 ${ps.status}`;
+                const detail = ps.description ? ` — ${ps.description}` : '';
+                prompt += `- ${ps.displayName}: ${statusLabel}${detail}\n`;
+            }
+            prompt += '\nNote: One or more infrastructure providers are experiencing issues. Consider whether this incident is caused by the provider outage rather than a code bug.\n\n';
+        }
         // Add monitor context if available
         if (monitor) {
             prompt += `**Service:** ${monitor.url}\n`;
@@ -89,6 +115,16 @@ Make the fix_prompt actionable enough that an AI coding assistant can implement
             }
             prompt += '\n';
         }
+        // Add trace waterfall if available
+        if (traces && traces.length > 0) {
+            const waterfall = buildTraceWaterfall(traces);
+            if (waterfall) {
+                prompt += `\n**Request Traces (from OpenTelemetry instrumentation):**\n`;
+                prompt += `These traces show the exact sequence of operations your app performed during the failing request(s).\n\n`;
+                prompt += waterfall;
+                prompt += '\n';
+            }
+        }
         // Add recent history if available
         if (recentHistory && recentHistory.length > 0) {
             prompt += `\n**Recent History (last 24 hours):**\n`;
@@ -113,6 +149,14 @@ Make the fix_prompt actionable enough that an AI coding assistant can implement
             'message',
             'type',
             'source',
+            'trace_id',
+            'span_id',
+            'service_name',
+            'operation_name',
+            'duration_ms',
+            'status_message',
+            'db_system',
+            'db_statement',
         ];
         for (const field of relevantFields) {
             if (field in data) {
@@ -134,6 +178,8 @@ Make the fix_prompt actionable enough that an AI coding assistant can implement
                 severity: this.normalizeSeverity(parsed.severity),
                 suggested_fix: parsed.suggested_fix || 'No fix suggested',
                 fix_prompt: parsed.fix_prompt || 'No fix prompt provided',
+                bottleneck_span: parsed.bottleneck_span || undefined,
+                trace_id: parsed.trace_id || undefined,
             };
         }
         catch (error) {
@@ -157,3 +203,126 @@ Make the fix_prompt actionable enough that an AI coding assistant can implement
     }
 }
 exports.Diagnoser = Diagnoser;
+/**
+ * Build a human-readable waterfall view of traces, grouped by trace_id.
+ * Each trace shows the root span and its children as an indented tree.
+ */
+function buildTraceWaterfall(spans) {
+    // Group spans by trace_id
+    const traceMap = new Map();
+    for (const span of spans) {
+        const group = traceMap.get(span.trace_id) || [];
+        group.push(span);
+        traceMap.set(span.trace_id, group);
+    }
+    const sections = [];
+    for (const [traceId, traceSpans] of traceMap) {
+        // Sort by start_time
+        traceSpans.sort((a, b) => a.start_time - b.start_time);
+        // Build a parent → children index
+        const childrenMap = new Map();
+        for (const span of traceSpans) {
+            const parentKey = span.parent_span_id;
+            const siblings = childrenMap.get(parentKey) || [];
+            siblings.push(span);
+            childrenMap.set(parentKey, siblings);
+        }
+        // Find root spans (no parent or parent not in this trace)
+        const spanIds = new Set(traceSpans.map((s) => s.span_id));
+        const roots = traceSpans.filter((s) => !s.parent_span_id || !spanIds.has(s.parent_span_id));
+        if (roots.length === 0)
+            continue;
+        let section = `\`\`\`\nTrace ${traceId}\n`;
+        for (const root of roots) {
+            section += renderSpanTree(root, childrenMap, '', true);
+        }
+        section += '```\n';
+        sections.push(section);
+        // Limit to 5 traces to keep prompt size reasonable
+        if (sections.length >= 5)
+            break;
+    }
+    return sections.join('\n');
+}
+/**
+ * Render a single span and its children as an indented tree.
+ */
+function renderSpanTree(span, childrenMap, prefix, isLast) {
+    const status = formatSpanStatus(span);
+    const label = formatSpanLabel(span);
+    const connector = prefix === '' ? '' : isLast ? '└─ ' : '├─ ';
+    let line = `${prefix}${connector}${label} (${span.duration_ms}ms) ${status}\n`;
+    // Add key attributes on a sub-line for context
+    const detail = formatSpanDetail(span);
+    if (detail) {
+        const detailPrefix = prefix === '' ? '   ' : prefix + (isLast ? '   ' : '│  ');
+        line += `${detailPrefix}${detail}\n`;
+    }
+    // Render children
+    const children = childrenMap.get(span.span_id) || [];
+    children.sort((a, b) => a.start_time - b.start_time);
+    const childPrefix = prefix === '' ? '' : prefix + (isLast ? '   ' : '│  ');
+    for (let i = 0; i < children.length; i++) {
+        line += renderSpanTree(children[i], childrenMap, childPrefix, i === children.length - 1);
+    }
+    return line;
+}
+function formatSpanLabel(span) {
+    const attrs = span.attributes;
+    // Database spans: show db.system + operation
+    if (attrs['db.system']) {
+        const stmt = attrs['db.statement'];
+        if (typeof stmt === 'string') {
+            const truncated = stmt.length > 80 ? stmt.substring(0, 80) + '...' : stmt;
+            return `${attrs['db.system']}: ${truncated}`;
+        }
+        return `${attrs['db.system']}: ${span.operation_name}`;
+    }
+    // HTTP spans: show method + route/target
+    const method = attrs['http.method'] || attrs['http.request.method'];
+    const route = attrs['http.route'] || attrs['http.target'] || attrs['url.path'];
+    if (method && route) {
+        return `${method} ${route}`;
+    }
+    return span.operation_name;
+}
+function formatSpanStatus(span) {
+    if (span.status_code === 'ERROR') {
+        const msg = span.status_message || 'error';
+        return `✗ ${msg}`;
+    }
+    if (span.status_code === 'OK') {
+        return '✓';
+    }
+    // UNSET — infer from http.status_code if available
+    const httpStatus = span.attributes['http.status_code'] || span.attributes['http.response.status_code'];
+    if (typeof httpStatus === 'number' && httpStatus >= 400) {
+        return `✗ HTTP ${httpStatus}`;
+    }
+    return '✓';
+}
+function formatSpanDetail(span) {
+    const parts = [];
+    const attrs = span.attributes;
+    // Error message from span events
+    if (span.status_code === 'ERROR') {
+        const exceptionEvent = span.events.find((e) => e.name === 'exception');
+        if (exceptionEvent?.attributes) {
+            const msg = exceptionEvent.attributes['exception.message'];
+            if (typeof msg === 'string') {
+                parts.push(`error: ${msg.length > 120 ? msg.substring(0, 120) + '...' : msg}`);
+            }
+        }
+    }
+    // HTTP status
+    const httpStatus = attrs['http.status_code'] || attrs['http.response.status_code'];
+    if (httpStatus) {
+        parts.push(`status: ${httpStatus}`);
+    }
+    // DB statement (if not already in label, show here for children)
+    if (attrs['db.statement'] && !attrs['db.system']) {
+        const stmt = String(attrs['db.statement']);
+        parts.push(stmt.length > 80 ? stmt.substring(0, 80) + '...' : stmt);
+    }
+    return parts.join(' | ');
+}

package/dist/types.d.ts

@@ -7,12 +7,12 @@ export interface Monitor {
     status: 'up' | 'down' | 'unknown';
     created_at: Date;
 }
-export type EventSource = 'monitor' | 'vercel' | 'stripe' | 'supabase' | 'github' | 'provider-status';
+export type EventSource = 'monitor' | 'vercel' | 'stripe' | 'supabase' | 'github' | 'provider-status' | 'otel';
 export interface Event {
     id: string;
     project_id: string;
     monitor_id?: string;
-    type: 'error' | 'slow' | 'down' | 'up';
+    type: 'error' | 'slow' | 'down' | 'up' | 'trace_error' | 'slow_query';
     source: EventSource;
     message: string;
     raw_data?: Record<string, unknown>;
@@ -60,6 +60,25 @@ export interface DiagnosisResult {
     severity: 'critical' | 'warning' | 'info';
     suggested_fix: string;
     fix_prompt: string;
+    bottleneck_span?: string;
+    trace_id?: string;
+}
+export interface TraceSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    service_name: string;
+    operation_name: string;
+    kind: string;
+    start_time: number;
+    duration_ms: number;
+    status_code: string | null;
+    status_message: string | null;
+    attributes: Record<string, unknown>;
+    events: Array<{
+        name: string;
+        attributes?: Record<string, unknown>;
+    }>;
 }
 export interface ProviderStatus {
     provider: string;

package/package.json

@@ -1,44 +1,47 @@
-{
-  "name": "@scanwarp/core",
-  "version": "0.2.0",
-  "description": "Shared types and logic for ScanWarp monitoring",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "monitoring",
-    "observability",
-    "ai",
-    "claude",
-    "diagnosis",
-    "production",
-    "incidents"
-  ],
-  "author": "ScanWarp",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/scanwarp/scanwarp.git",
-    "directory": "packages/core"
-  },
-  "bugs": {
-    "url": "https://github.com/scanwarp/scanwarp/issues"
-  },
-  "homepage": "https://scanwarp.com",
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "typescript": "^5.3.3"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.74.0"
-  }
-}
+{
+  "name": "@scanwarp/core",
+  "version": "0.3.0",
+  "description": "Shared types and logic for ScanWarp monitoring",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "monitoring",
+    "observability",
+    "ai",
+    "claude",
+    "diagnosis",
+    "production",
+    "incidents"
+  ],
+  "author": "ScanWarp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scanwarp/scanwarp.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/scanwarp/scanwarp/issues"
+  },
+  "homepage": "https://scanwarp.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0"
+  }
+}