/** * Detector automático de padrões sobre a BD `sessions` (Observabilidade Fase 6A). * * Seis detectores heurísticos em SQL puro (via better-sqlite3). Cada detector * devolve zero ou mais `Pattern` para a semana analisada. Pipeline: * 1. Correr detectores sobre intervalo [weekStart, weekEnd] * 2. Persistir via `upsertPattern` (idempotente por (week_iso, pattern_key)) * 3. Calcular `consecutive_weeks` olhando para semanas anteriores */ import type Database from 'better-sqlite3' import type { SessionsDb, PatternRecord } from './db.js' export type Severity = 'info' | 'warning' | 'action' export interface Pattern { pattern_key: string title: string description: string severity: Severity metric_value: number | null sample_session_ids: string[] affected_count: number } export interface DetectCtx { db: Database.Database weekStartIso: string weekEndIso: string } /** Converte Date para string ISO UTC. */ function iso(d: Date): string { return d.toISOString() } /** * Calcula intervalo [segunda 00:00:00 UTC, domingo 23:59:59.999 UTC] da semana * que contém `ref` (Regra 17 — semana começa à segunda). */ export function weekRange(ref: Date): { start: Date; end: Date; iso: string } { const d = new Date(Date.UTC(ref.getUTCFullYear(), ref.getUTCMonth(), ref.getUTCDate())) const dow = d.getUTCDay() // 0=Dom, 1=Seg const diffToMonday = dow === 0 ? -6 : 1 - dow const start = new Date(d) start.setUTCDate(d.getUTCDate() + diffToMonday) const end = new Date(start) end.setUTCDate(start.getUTCDate() + 6) end.setUTCHours(23, 59, 59, 999) return { start, end, iso: weekIso(start) } } /** Semana ISO 8601 (YYYY-Www) para segunda de referência. */ export function weekIso(monday: Date): string { // Usa algoritmo ISO: quinta da mesma semana determina o ano const thursday = new Date(monday) thursday.setUTCDate(monday.getUTCDate() + 3) const year = thursday.getUTCFullYear() const jan1 = new Date(Date.UTC(year, 0, 1)) const week = Math.floor( ((thursday.getTime() - jan1.getTime()) / 86400000 + (jan1.getUTCDay() === 0 ? 6 : jan1.getUTCDay() - 1)) / 7 ) + 1 return `${year}-W${String(week).padStart(2, '0')}` } /** Helper: todos os session_ids no intervalo. */ function baseRows(ctx: DetectCtx) { return ctx.db.prepare(` SELECT session_id, project_slug, started_at, event_count, tool_calls, tools_used, skills_invoked, outcome, duration_sec FROM sessions WHERE started_at >= ? AND started_at <= ? `).all(ctx.weekStartIso, ctx.weekEndIso) as Array<{ session_id: string project_slug: string started_at: string event_count: number tool_calls: number tools_used: string skills_invoked: string outcome: string duration_sec: number | null }> } /** 1. Skills com taxa elevada de erro/interrupção. */ export function detectSkillsHighErrorRate(ctx: DetectCtx): Pattern[] { const rows = baseRows(ctx) // Agregar por skill const bySkill = new Map() for (const r of rows) { let skills: string[] = [] try { skills = JSON.parse(r.skills_invoked) } catch {} for (const sk of skills) { const entry = bySkill.get(sk) ?? { total: 0, fail: 0, ids: [] } entry.total++ if (r.outcome === 'error' || r.outcome === 'interrupted') { entry.fail++ if (entry.ids.length < 5) entry.ids.push(r.session_id) } bySkill.set(sk, entry) } } const out: Pattern[] = [] for (const [skill, v] of bySkill) { if (v.total < 3) continue const ratio = v.fail / v.total if (ratio <= 0.2) continue const severity: Severity = ratio > 0.4 ? 'action' : 'warning' out.push({ pattern_key: `skill_error_rate:${skill}`, title: `Skill ${skill}: ${(ratio * 100).toFixed(0)}% das sessões falham`, description: `De ${v.total} sessões que invocaram ${skill}, ${v.fail} terminaram em erro/interrupção.`, severity, metric_value: Math.round(ratio * 1000) / 1000, sample_session_ids: v.ids, affected_count: v.fail, }) } return out } /** 2. Tools com baixa eficiência (tool_calls/event_count elevado). */ export function detectToolsLowEfficiency(ctx: DetectCtx): Pattern[] { const rows = baseRows(ctx) const byTool = new Map() for (const r of rows) { if (!r.event_count || r.event_count === 0) continue const ratio = r.tool_calls / r.event_count let tools: string[] = [] try { tools = JSON.parse(r.tools_used) } catch {} for (const t of tools) { const e = byTool.get(t) ?? { sum: 0, count: 0, ids: [] } e.sum += ratio e.count++ if (e.ids.length < 5) e.ids.push(r.session_id) byTool.set(t, e) } } const out: Pattern[] = [] for (const [tool, v] of byTool) { if (v.count < 5) continue const avg = v.sum / v.count if (avg <= 0.5) continue out.push({ pattern_key: `tool_low_efficiency:${tool}`, title: `Tool ${tool}: rácio tool_calls/event_count médio ${avg.toFixed(2)}`, description: `Em ${v.count} sessões, ${tool} domina o event_count. Indício de uso ineficiente ou looping.`, severity: 'info', metric_value: Math.round(avg * 1000) / 1000, sample_session_ids: v.ids, affected_count: v.count, }) } return out } /** 3. Pares (skill, tool) mais frequentes. */ export function detectSkillToolPairs(ctx: DetectCtx): Pattern[] { const rows = baseRows(ctx) const byPair = new Map() for (const r of rows) { let skills: string[] = [] let tools: string[] = [] try { skills = JSON.parse(r.skills_invoked) } catch {} try { tools = JSON.parse(r.tools_used) } catch {} for (const s of skills) { for (const t of tools) { const key = `${s}::${t}` const e = byPair.get(key) ?? { count: 0, ids: [] } e.count++ if (e.ids.length < 5) e.ids.push(r.session_id) byPair.set(key, e) } } } const sorted = [...byPair.entries()].filter(([, v]) => v.count >= 5).sort((a, b) => b[1].count - a[1].count).slice(0, 5) return sorted.map(([key, v]) => ({ pattern_key: `skill_tool_pair:${key}`, title: `Par frequente: ${key.replace('::', ' + ')}`, description: `Skill e tool co-ocorreram em ${v.count} sessões esta semana.`, severity: 'info' as Severity, metric_value: v.count, sample_session_ids: v.ids, affected_count: v.count, })) } /** 4. Duration outliers: sessões > p95 por projecto com outcome != completed. */ export function detectDurationOutliers(ctx: DetectCtx): Pattern[] { const rows = baseRows(ctx).filter((r) => r.duration_sec != null && r.duration_sec > 0) const byProject = new Map>() for (const r of rows) { const arr = byProject.get(r.project_slug) ?? [] arr.push(r) byProject.set(r.project_slug, arr) } const out: Pattern[] = [] for (const [proj, arr] of byProject) { if (arr.length < 4) continue const durations = arr.map((r) => r.duration_sec as number).sort((a, b) => a - b) const p95Idx = Math.max(0, Math.floor(durations.length * 0.95) - 1) const p95 = durations[p95Idx] const outliers = arr.filter((r) => (r.duration_sec as number) > p95 && r.outcome !== 'completed') if (outliers.length < 3) continue out.push({ pattern_key: `duration_outliers:${proj}`, title: `Projecto ${proj}: ${outliers.length} sessões longas não concluídas`, description: `Sessões com duração acima do p95 (${p95}s) e outcome != completed. Sinal de sessões penduradas.`, severity: 'warning', metric_value: p95, sample_session_ids: outliers.slice(0, 5).map((r) => r.session_id), affected_count: outliers.length, }) } return out } /** 5. Sessões abandonadas (event_count < 3 AND outcome=unknown). */ export function detectAbandonedSessions(ctx: DetectCtx): Pattern[] { const rows = ctx.db.prepare(` SELECT session_id FROM sessions WHERE started_at >= ? AND started_at <= ? AND event_count < 3 AND outcome = 'unknown' `).all(ctx.weekStartIso, ctx.weekEndIso) as Array<{ session_id: string }> if (rows.length < 5) return [] return [{ pattern_key: 'abandoned_sessions', title: `${rows.length} sessões abandonadas esta semana`, description: `Sessões com menos de 3 eventos e outcome=unknown — tipicamente abertas e descartadas.`, severity: 'info', metric_value: rows.length, sample_session_ids: rows.slice(0, 5).map((r) => r.session_id), affected_count: rows.length, }] } /** 6. Crescimento de complexidade: avg(tool_calls) actual vs semana anterior. */ export function detectGrowingComplexity(ctx: DetectCtx, prevWeekStartIso: string, prevWeekEndIso: string): Pattern[] { const curRows = baseRows(ctx) const prevRows = ctx.db.prepare(` SELECT skills_invoked, tool_calls FROM sessions WHERE started_at >= ? AND started_at <= ? `).all(prevWeekStartIso, prevWeekEndIso) as Array<{ skills_invoked: string; tool_calls: number }> const curBySkill = new Map() for (const r of curRows) { let sk: string[] = [] try { sk = JSON.parse(r.skills_invoked) } catch {} for (const s of sk) { const e = curBySkill.get(s) ?? { sum: 0, count: 0, ids: [] } e.sum += r.tool_calls e.count++ if (e.ids.length < 5) e.ids.push(r.session_id) curBySkill.set(s, e) } } const prevBySkill = new Map() for (const r of prevRows) { let sk: string[] = [] try { sk = JSON.parse(r.skills_invoked) } catch {} for (const s of sk) { const e = prevBySkill.get(s) ?? { sum: 0, count: 0 } e.sum += r.tool_calls e.count++ prevBySkill.set(s, e) } } const out: Pattern[] = [] for (const [skill, cur] of curBySkill) { if (cur.count < 5) continue const curAvg = cur.sum / cur.count const prev = prevBySkill.get(skill) if (!prev || prev.count < 3) continue const prevAvg = prev.sum / prev.count if (prevAvg === 0 || curAvg <= prevAvg * 1.3) continue out.push({ pattern_key: `growing_complexity:${skill}`, title: `Skill ${skill}: tool_calls médio +${Math.round((curAvg / prevAvg - 1) * 100)}% vs semana anterior`, description: `Média de tool_calls/sessão subiu de ${prevAvg.toFixed(1)} para ${curAvg.toFixed(1)}.`, severity: 'warning', metric_value: Math.round(curAvg * 10) / 10, sample_session_ids: cur.ids, affected_count: cur.count, }) } return out } /** Orquestra todos os detectores para a semana indicada. */ export function detectPatterns( dbWrapper: SessionsDb, weekStart: Date, weekEnd: Date, ): Pattern[] { const db = dbWrapper.rawDb() const ctx: DetectCtx = { db, weekStartIso: iso(weekStart), weekEndIso: iso(weekEnd), } const prevStart = new Date(weekStart); prevStart.setUTCDate(prevStart.getUTCDate() - 7) const prevEnd = new Date(weekEnd); prevEnd.setUTCDate(prevEnd.getUTCDate() - 7) return [ ...detectSkillsHighErrorRate(ctx), ...detectToolsLowEfficiency(ctx), ...detectSkillToolPairs(ctx), ...detectDurationOutliers(ctx), ...detectAbandonedSessions(ctx), ...detectGrowingComplexity(ctx, iso(prevStart), iso(prevEnd)), ] } /** Converte Pattern + contexto em PatternRecord pronto a persistir. */ export function toPatternRecord(p: Pattern, weekIso: string, consecutiveWeeks: number): PatternRecord { return { detected_at: new Date().toISOString(), week_iso: weekIso, pattern_key: p.pattern_key, title: p.title, description: p.description, severity: p.severity, metric_value: p.metric_value, sample_session_ids: p.sample_session_ids, affected_count: p.affected_count, consecutive_weeks: consecutiveWeeks, } }