opencastle 0.31.6 → 0.32.0

package/src/cli/convoy/dag-analysis.ts

@@ -0,0 +1,371 @@
+import type { ConvoyStore } from './store.js'
+import type { ConvoyRecord, TaskRecord } from './types.js'
+
+export interface ConvoyPattern {
+  name: string
+  task_count_range: [number, number]
+  agent_sequence: string[]
+  avg_duration_ms: number
+  avg_tokens: number
+  success_rate: number
+  common_failure_agents: string[]
+  recommended_concurrency: number
+  sample_size: number
+}
+
+export interface AgentPerformance {
+  agent: string
+  total_tasks: number
+  success_rate: number
+  avg_duration_ms: number
+  avg_tokens: number
+  avg_retries: number
+  best_file_patterns: string[]
+  worst_file_patterns: string[]
+}
+
+export interface DAGRecommendation {
+  patterns: ConvoyPattern[]
+  agent_stats: AgentPerformance[]
+  insights: string[]
+  generated_at: string
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function taskBucket(count: number): string {
+  if (count <= 2) return 'small'
+  if (count <= 5) return 'medium'
+  if (count <= 10) return 'large'
+  return 'xlarge'
+}
+
+function extractConcurrency(specYaml: string | null | undefined): number {
+  if (!specYaml) return 1
+  const m = specYaml.match(/concurrency:\s*(\d+)/)
+  return m ? parseInt(m[1], 10) : 1
+}
+
+function modeNum(values: number[]): number {
+  if (values.length === 0) return 1
+  const freq: Record<number, number> = {}
+  for (const v of values) freq[v] = (freq[v] ?? 0) + 1
+  let best = values[0]
+  let bestFreq = 0
+  for (const [k, f] of Object.entries(freq)) {
+    if (f > bestFreq) { bestFreq = f; best = Number(k) }
+  }
+  return best
+}
+
+function filePrefix(filePath: string): string {
+  const parts = filePath.split('/')
+  if (parts.length <= 2) return parts[0] ?? ''
+  return parts.slice(0, 2).join('/')
+}
+
+function avg(nums: number[]): number {
+  if (nums.length === 0) return 0
+  return nums.reduce((a, b) => a + b, 0) / nums.length
+}
+
+// ── public API ────────────────────────────────────────────────────────────────
+
+export function extractExecutionHistory(
+  store: ConvoyStore,
+  sinceDays = 90,
+): { convoys: ConvoyRecord[]; tasks: TaskRecord[] } {
+  const allConvoys = store.getConvoyList(10000, 0)
+  const cutoff = Date.now() - sinceDays * 24 * 60 * 60 * 1000
+
+  const convoys = allConvoys.filter((c) => {
+    if (c.status !== 'done' && c.status !== 'failed') return false
+    if (!c.finished_at) return false
+    return new Date(c.finished_at).getTime() >= cutoff
+  })
+
+  const tasks: TaskRecord[] = []
+  for (const convoy of convoys) {
+    const convoyTasks = store.getTasksByConvoy(convoy.id)
+    tasks.push(...convoyTasks)
+  }
+
+  return { convoys, tasks }
+}
+
+export function clusterConvoys(
+  convoys: ConvoyRecord[],
+  tasks: TaskRecord[],
+): ConvoyPattern[] {
+  const tasksByConvoy = new Map<string, TaskRecord[]>()
+  for (const t of tasks) {
+    const list = tasksByConvoy.get(t.convoy_id) ?? []
+    list.push(t)
+    tasksByConvoy.set(t.convoy_id, list)
+  }
+
+  type ClusterEntry = { convoys: ConvoyRecord[]; convoyTasks: TaskRecord[][] }
+  const clusters = new Map<string, ClusterEntry>()
+
+  for (const convoy of convoys) {
+    const convoyTasks = tasksByConvoy.get(convoy.id) ?? []
+    const count = convoyTasks.length
+    const bucket = taskBucket(count)
+    const agentSet = [...new Set(convoyTasks.map((t) => t.agent))].sort()
+    const key = `${bucket}|${agentSet.join(',')}`
+
+    const existing = clusters.get(key) ?? { convoys: [], convoyTasks: [] }
+    existing.convoys.push(convoy)
+    existing.convoyTasks.push(convoyTasks)
+    clusters.set(key, existing)
+  }
+
+  const patterns: ConvoyPattern[] = []
+
+  for (const [key, { convoys: clusterConvoys, convoyTasks }] of clusters) {
+    const sepIdx = key.indexOf('|')
+    const bucket = key.slice(0, sepIdx)
+    const agentStr = key.slice(sepIdx + 1)
+    const agentSeq = agentStr ? agentStr.split(',').filter(Boolean) : []
+
+    const durations: number[] = []
+    for (const c of clusterConvoys) {
+      if (c.started_at && c.finished_at) {
+        durations.push(new Date(c.finished_at).getTime() - new Date(c.started_at).getTime())
+      }
+    }
+
+    const tokenValues: number[] = clusterConvoys
+      .filter((c) => c.total_tokens != null)
+      .map((c) => c.total_tokens as number)
+
+    const successCount = clusterConvoys.filter((c) => c.status === 'done').length
+    const successRate = clusterConvoys.length > 0 ? successCount / clusterConvoys.length : 0
+
+    const agentFailCounts: Record<string, { failed: number; total: number }> = {}
+    for (const taskList of convoyTasks) {
+      for (const t of taskList) {
+        const entry = agentFailCounts[t.agent] ?? { failed: 0, total: 0 }
+        entry.total++
+        if (t.status === 'failed') entry.failed++
+        agentFailCounts[t.agent] = entry
+      }
+    }
+    const commonFailureAgents = Object.entries(agentFailCounts)
+      .filter(([, v]) => v.total > 0 && v.failed / v.total > 0.2)
+      .map(([agent]) => agent)
+
+    const successfulConvoys = clusterConvoys.filter((c) => c.status === 'done')
+    const concurrencies = successfulConvoys.map((c) => extractConcurrency(c.spec_yaml))
+    const recommendedConcurrency = modeNum(concurrencies.length > 0 ? concurrencies : [1])
+
+    const counts = convoyTasks.map((tl) => tl.length)
+    const bucketMinMap: Record<string, number> = { small: 1, medium: 3, large: 6, xlarge: 11 }
+    const minCount = counts.length > 0 ? Math.min(...counts) : (bucketMinMap[bucket] ?? 1)
+    const maxCount = counts.length > 0 ? Math.max(...counts) : 0
+
+    const agentLabel =
+      agentSeq.length === 0
+        ? 'empty'
+        : agentSeq.length === 1
+          ? agentSeq[0]
+          : agentSeq.slice(0, 2).join('-')
+    const name = `${bucket}-${agentLabel}`
+
+    patterns.push({
+      name,
+      task_count_range: [minCount, maxCount],
+      agent_sequence: agentSeq,
+      avg_duration_ms: avg(durations),
+      avg_tokens: avg(tokenValues),
+      success_rate: successRate,
+      common_failure_agents: commonFailureAgents,
+      recommended_concurrency: recommendedConcurrency,
+      sample_size: clusterConvoys.length,
+    })
+  }
+
+  return patterns
+}
+
+export function analyzeAgentPerformance(tasks: TaskRecord[]): AgentPerformance[] {
+  const byAgent = new Map<string, TaskRecord[]>()
+  for (const t of tasks) {
+    const list = byAgent.get(t.agent) ?? []
+    list.push(t)
+    byAgent.set(t.agent, list)
+  }
+
+  const results: AgentPerformance[] = []
+
+  for (const [agent, agentTasks] of byAgent) {
+    const totalTasks = agentTasks.length
+    const doneCount = agentTasks.filter((t) => t.status === 'done').length
+    const successRate = totalTasks > 0 ? doneCount / totalTasks : 0
+
+    const durations = agentTasks
+      .filter((t) => t.started_at != null && t.finished_at != null)
+      .map((t) => new Date(t.finished_at!).getTime() - new Date(t.started_at!).getTime())
+
+    const tokenValues = agentTasks
+      .filter((t) => t.total_tokens != null)
+      .map((t) => t.total_tokens as number)
+
+    const avgRetries = avg(agentTasks.map((t) => t.retries))
+
+    const prefixStats = new Map<string, { done: number; total: number }>()
+    for (const t of agentTasks) {
+      if (!t.files) continue
+      let fileList: string[]
+      try {
+        fileList = JSON.parse(t.files) as string[]
+      } catch {
+        continue
+      }
+      if (!Array.isArray(fileList)) continue
+      for (const f of fileList) {
+        const prefix = filePrefix(f)
+        if (!prefix) continue
+        const entry = prefixStats.get(prefix) ?? { done: 0, total: 0 }
+        entry.total++
+        if (t.status === 'done') entry.done++
+        prefixStats.set(prefix, entry)
+      }
+    }
+
+    const eligiblePrefixes = [...prefixStats.entries()].filter(([, v]) => v.total >= 2)
+    const sorted = eligiblePrefixes.sort(([, a], [, b]) => b.done / b.total - a.done / a.total)
+
+    const bestFilePatterns = sorted
+      .filter(([, v]) => v.done / v.total >= 0.8)
+      .slice(0, 3)
+      .map(([prefix]) => prefix)
+
+    const worstFilePatterns = [...sorted]
+      .reverse()
+      .filter(([, v]) => v.done / v.total <= 0.5)
+      .slice(0, 3)
+      .map(([prefix]) => prefix)
+
+    results.push({
+      agent,
+      total_tasks: totalTasks,
+      success_rate: successRate,
+      avg_duration_ms: avg(durations),
+      avg_tokens: avg(tokenValues),
+      avg_retries: avgRetries,
+      best_file_patterns: bestFilePatterns,
+      worst_file_patterns: worstFilePatterns,
+    })
+  }
+
+  return results
+}
+
+export function generateInsights(
+  patterns: ConvoyPattern[],
+  agents: AgentPerformance[],
+): string[] {
+  if (patterns.length === 0 && agents.length === 0) {
+    return ['No execution history available yet. Run some convoys first.']
+  }
+
+  const insights: string[] = []
+
+  for (const agent of agents) {
+    const ratePct = Math.round(agent.success_rate * 100)
+    if (agent.success_rate < 0.7) {
+      insights.push(
+        `⚠️ ${agent.agent} has a ${ratePct}% success rate — consider splitting tasks smaller or providing more context`,
+      )
+    }
+    if (agent.avg_retries > 1.5) {
+      insights.push(
+        `⚠️ ${agent.agent} has a ${agent.avg_retries.toFixed(1)}x average retry rate — investigate common failure causes`,
+      )
+    }
+    if (agent.best_file_patterns.length > 0) {
+      const bestRate = Math.round(agent.success_rate * 100)
+      insights.push(
+        `✓ ${agent.agent} excels on ${agent.best_file_patterns.join(', ')} (${bestRate}% success rate)`,
+      )
+    }
+    if (agent.success_rate === 1 && agent.total_tasks >= 3) {
+      insights.push(
+        `✓ ${agent.agent} has 100% success — auto-PASS review may be safe`,
+      )
+    }
+  }
+
+  for (const pattern of patterns) {
+    const durationMin = Math.round(pattern.avg_duration_ms / 60000)
+    insights.push(
+      `Convoys with ${pattern.task_count_range[0]}–${pattern.task_count_range[1]} tasks perform best at concurrency ${pattern.recommended_concurrency} (avg ${durationMin}min)`,
+    )
+  }
+
+  return insights
+}
+
+export function analyzeDAG(
+  store: ConvoyStore,
+  sinceDays?: number,
+): DAGRecommendation {
+  const { convoys, tasks } = extractExecutionHistory(store, sinceDays)
+  const patterns = clusterConvoys(convoys, tasks)
+  const agent_stats = analyzeAgentPerformance(tasks)
+  const insights = generateInsights(patterns, agent_stats)
+
+  return {
+    patterns,
+    agent_stats,
+    insights,
+    generated_at: new Date().toISOString(),
+  }
+}
+
+export function formatInsightsMarkdown(rec: DAGRecommendation): string {
+  const lines: string[] = []
+
+  lines.push('## Convoy Patterns\n')
+  if (rec.patterns.length === 0) {
+    lines.push('_No pattern data available._\n')
+  } else {
+    lines.push('| Name | Task Range | Success Rate | Concurrency | Samples |')
+    lines.push('|------|-----------|-------------|-------------|---------|')
+    for (const p of rec.patterns) {
+      const rate = `${Math.round(p.success_rate * 100)}%`
+      lines.push(
+        `| ${p.name} | ${p.task_count_range[0]}–${p.task_count_range[1]} | ${rate} | ${p.recommended_concurrency} | ${p.sample_size} |`,
+      )
+    }
+    lines.push('')
+  }
+
+  lines.push('## Agent Performance\n')
+  if (rec.agent_stats.length === 0) {
+    lines.push('_No agent data available._\n')
+  } else {
+    lines.push('| Agent | Tasks | Success Rate | Avg Duration | Avg Retries |')
+    lines.push('|-------|-------|-------------|-------------|-------------|')
+    for (const a of rec.agent_stats) {
+      const rate = `${Math.round(a.success_rate * 100)}%`
+      const dur = a.avg_duration_ms > 0 ? `${Math.round(a.avg_duration_ms / 1000)}s` : '—'
+      lines.push(
+        `| ${a.agent} | ${a.total_tasks} | ${rate} | ${dur} | ${a.avg_retries.toFixed(1)} |`,
+      )
+    }
+    lines.push('')
+  }
+
+  lines.push('## Recommendations\n')
+  for (const insight of rec.insights) {
+    lines.push(`- ${insight}`)
+  }
+
+  return lines.join('\n')
+}
+
+export function formatInsightsJSON(rec: DAGRecommendation): string {
+  return JSON.stringify(rec, null, 2)
+}

package/src/cli/convoy/effort-scaling.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from 'vitest'
+import { getEffortProfile, EFFORT_TABLE } from './effort-scaling.js'
+
+describe('getEffortProfile', () => {
+  it('returns complexity-1 profile for score 1', () => {
+    const p = getEffortProfile(1)
+    expect(p.complexity).toBe(1)
+    expect(p.tier).toBe('economy')
+    expect(p.timeout).toBe('5m')
+    expect(p.max_retries).toBe(1)
+    expect(p.review).toBe('auto')
+    expect(p.expected_tokens).toBe(5000)
+  })
+
+  it('returns complexity-2 profile for score 2', () => {
+    const p = getEffortProfile(2)
+    expect(p.complexity).toBe(2)
+    expect(p.tier).toBe('economy')
+    expect(p.timeout).toBe('10m')
+    expect(p.max_retries).toBe(1)
+    expect(p.review).toBe('auto')
+    expect(p.expected_tokens).toBe(15000)
+  })
+
+  it('returns complexity-3 profile for score 3', () => {
+    const p = getEffortProfile(3)
+    expect(p.complexity).toBe(3)
+    expect(p.tier).toBe('standard')
+    expect(p.timeout).toBe('15m')
+    expect(p.max_retries).toBe(2)
+    expect(p.review).toBe('fast')
+    expect(p.expected_tokens).toBe(30000)
+  })
+
+  it('returns complexity-5 profile for score 5', () => {
+    const p = getEffortProfile(5)
+    expect(p.complexity).toBe(5)
+    expect(p.tier).toBe('standard')
+    expect(p.timeout).toBe('20m')
+    expect(p.max_retries).toBe(2)
+    expect(p.review).toBe('fast')
+    expect(p.expected_tokens).toBe(60000)
+  })
+
+  it('returns complexity-8 profile for score 8', () => {
+    const p = getEffortProfile(8)
+    expect(p.complexity).toBe(8)
+    expect(p.tier).toBe('standard')
+    expect(p.timeout).toBe('30m')
+    expect(p.max_retries).toBe(2)
+    expect(p.review).toBe('fast')
+    expect(p.expected_tokens).toBe(120000)
+  })
+
+  it('returns complexity-13 profile for score 13', () => {
+    const p = getEffortProfile(13)
+    expect(p.complexity).toBe(13)
+    expect(p.tier).toBe('premium')
+    expect(p.timeout).toBe('45m')
+    expect(p.max_retries).toBe(3)
+    expect(p.review).toBe('panel')
+    expect(p.expected_tokens).toBe(250000)
+  })
+
+  it('rounds up score 4 to complexity-5 profile', () => {
+    const p = getEffortProfile(4)
+    expect(p.complexity).toBe(5)
+  })
+
+  it('rounds up score 6 to complexity-8 profile', () => {
+    const p = getEffortProfile(6)
+    expect(p.complexity).toBe(8)
+  })
+
+  it('rounds up score 7 to complexity-8 profile', () => {
+    const p = getEffortProfile(7)
+    expect(p.complexity).toBe(8)
+  })
+
+  it('rounds up score 9 to complexity-13 profile', () => {
+    const p = getEffortProfile(9)
+    expect(p.complexity).toBe(13)
+  })
+
+  it('rounds up score 10 to complexity-13 profile', () => {
+    const p = getEffortProfile(10)
+    expect(p.complexity).toBe(13)
+  })
+
+  it('rounds up score 12 to complexity-13 profile', () => {
+    const p = getEffortProfile(12)
+    expect(p.complexity).toBe(13)
+  })
+
+  it('clamps score 0 to complexity-1 profile', () => {
+    const p = getEffortProfile(0)
+    expect(p.complexity).toBe(1)
+  })
+
+  it('clamps negative score -5 to complexity-1 profile', () => {
+    const p = getEffortProfile(-5)
+    expect(p.complexity).toBe(1)
+  })
+
+  it('clamps large negative score -9999 to complexity-1 profile', () => {
+    const p = getEffortProfile(-9999)
+    expect(p.complexity).toBe(1)
+  })
+
+  it('clamps score 14 to complexity-13 profile', () => {
+    const p = getEffortProfile(14)
+    expect(p.complexity).toBe(13)
+  })
+
+  it('clamps score 100 to complexity-13 profile', () => {
+    const p = getEffortProfile(100)
+    expect(p.complexity).toBe(13)
+  })
+
+  it('clamps very large score 9999 to complexity-13 profile', () => {
+    const p = getEffortProfile(9999)
+    expect(p.complexity).toBe(13)
+  })
+
+  it('returns the same object reference from EFFORT_TABLE for exact matches', () => {
+    for (const entry of EFFORT_TABLE) {
+      expect(getEffortProfile(entry.complexity)).toBe(entry)
+    }
+  })
+
+  it('EFFORT_TABLE has 6 entries', () => {
+    expect(EFFORT_TABLE).toHaveLength(6)
+  })
+
+  it('EFFORT_TABLE entries are ordered by ascending complexity', () => {
+    for (let i = 1; i < EFFORT_TABLE.length; i++) {
+      expect(EFFORT_TABLE[i].complexity).toBeGreaterThan(EFFORT_TABLE[i - 1].complexity)
+    }
+  })
+})

package/src/cli/convoy/effort-scaling.ts

@@ -0,0 +1,90 @@
+export interface EffortProfile {
+  complexity: number
+  tier: 'economy' | 'standard' | 'utility' | 'premium'
+  max_agents: number
+  timeout: string
+  max_retries: number
+  review: 'none' | 'auto' | 'fast' | 'panel'
+  expected_tokens: number
+  description: string
+}
+
+export const EFFORT_TABLE: EffortProfile[] = [
+  {
+    complexity: 1,
+    tier: 'economy',
+    max_agents: 1,
+    timeout: '5m',
+    max_retries: 1,
+    review: 'auto',
+    expected_tokens: 5_000,
+    description: 'Trivial — single file edit, copy change, config tweak',
+  },
+  {
+    complexity: 2,
+    tier: 'economy',
+    max_agents: 1,
+    timeout: '10m',
+    max_retries: 1,
+    review: 'auto',
+    expected_tokens: 15_000,
+    description: 'Simple — small bug fix, add a test, update docs',
+  },
+  {
+    complexity: 3,
+    tier: 'standard',
+    max_agents: 1,
+    timeout: '15m',
+    max_retries: 2,
+    review: 'fast',
+    expected_tokens: 30_000,
+    description: 'Moderate — new component, API endpoint, or utility',
+  },
+  {
+    complexity: 5,
+    tier: 'standard',
+    max_agents: 2,
+    timeout: '20m',
+    max_retries: 2,
+    review: 'fast',
+    expected_tokens: 60_000,
+    description: 'Significant — multi-file feature, integration work',
+  },
+  {
+    complexity: 8,
+    tier: 'standard',
+    max_agents: 3,
+    timeout: '30m',
+    max_retries: 2,
+    review: 'fast',
+    expected_tokens: 120_000,
+    description: 'Complex — cross-cutting feature, schema change + UI + tests',
+  },
+  {
+    complexity: 13,
+    tier: 'premium',
+    max_agents: 5,
+    timeout: '45m',
+    max_retries: 3,
+    review: 'panel',
+    expected_tokens: 250_000,
+    description: 'Epic — architecture change, security overhaul, major refactor',
+  },
+]
+
+/**
+ * Returns the EffortProfile for a given complexity score.
+ * - Exact match: returns that profile
+ * - Between defined values: rounds up to the next profile
+ * - Below 1: returns the complexity-1 profile
+ * - Above 13: returns the complexity-13 profile
+ */
+export function getEffortProfile(complexity: number): EffortProfile {
+  if (complexity <= EFFORT_TABLE[0].complexity) return EFFORT_TABLE[0]
+  const last = EFFORT_TABLE[EFFORT_TABLE.length - 1]
+  if (complexity >= last.complexity) return last
+  for (const profile of EFFORT_TABLE) {
+    if (complexity <= profile.complexity) return profile
+  }
+  return last
+}