opencastle 0.31.6 → 0.32.0

package/src/cli/convoy/contracts.ts

@@ -0,0 +1,280 @@
+export interface FieldSpec {
+  type: 'string' | 'string[]' | 'number' | 'boolean' | 'object'
+  description: string
+  validation?: 'non-empty' | 'file-paths' | 'positive-int'
+}
+
+export interface OutputContract {
+  agent: string
+  required_fields: string[]
+  optional_fields: string[]
+  schema: Record<string, FieldSpec>
+}
+
+export interface ContractResult {
+  valid: boolean
+  missing: string[]
+  warnings: string[]
+  data?: Record<string, unknown>
+}
+
+export const AGENT_CONTRACTS: Record<string, OutputContract> = {
+  'developer': {
+    agent: 'developer',
+    required_fields: ['files_changed', 'tests_added', 'summary'],
+    optional_fields: [],
+    schema: {
+      files_changed: { type: 'string[]', description: 'List of file paths created or modified', validation: 'file-paths' },
+      tests_added: { type: 'string[]', description: 'List of test file paths added or modified', validation: 'file-paths' },
+      summary: { type: 'string', description: 'Brief description of what was implemented', validation: 'non-empty' },
+    },
+  },
+  'ui-ux-expert': {
+    agent: 'ui-ux-expert',
+    required_fields: ['files_changed', 'components_created', 'a11y_verified', 'summary'],
+    optional_fields: [],
+    schema: {
+      files_changed: { type: 'string[]', description: 'List of file paths created or modified', validation: 'file-paths' },
+      components_created: { type: 'string[]', description: 'List of new component file paths', validation: 'file-paths' },
+      a11y_verified: { type: 'boolean', description: 'Whether accessibility was verified' },
+      summary: { type: 'string', description: 'Brief description of UI/UX changes', validation: 'non-empty' },
+    },
+  },
+  'testing-expert': {
+    agent: 'testing-expert',
+    required_fields: ['test_files', 'coverage_summary', 'summary'],
+    optional_fields: [],
+    schema: {
+      test_files: { type: 'string[]', description: 'List of test file paths created or modified', validation: 'file-paths' },
+      coverage_summary: { type: 'string', description: 'Summary of test coverage achieved', validation: 'non-empty' },
+      summary: { type: 'string', description: 'Brief description of testing work done', validation: 'non-empty' },
+    },
+  },
+  'security-expert': {
+    agent: 'security-expert',
+    required_fields: ['findings', 'severity', 'files_reviewed', 'summary'],
+    optional_fields: [],
+    schema: {
+      findings: { type: 'string[]', description: 'List of security findings or issues found' },
+      severity: { type: 'string', description: 'Overall severity level (critical|high|medium|low|none)', validation: 'non-empty' },
+      files_reviewed: { type: 'string[]', description: 'List of file paths reviewed', validation: 'file-paths' },
+      summary: { type: 'string', description: 'Summary of security review', validation: 'non-empty' },
+    },
+  },
+  'architect': {
+    agent: 'architect',
+    required_fields: ['decision', 'alternatives_considered', 'risks', 'summary'],
+    optional_fields: [],
+    schema: {
+      decision: { type: 'string', description: 'The architectural decision made', validation: 'non-empty' },
+      alternatives_considered: { type: 'string', description: 'Alternatives that were evaluated', validation: 'non-empty' },
+      risks: { type: 'string', description: 'Known risks of the decision', validation: 'non-empty' },
+      summary: { type: 'string', description: 'Brief summary of the architectural decision', validation: 'non-empty' },
+    },
+  },
+  'researcher': {
+    agent: 'researcher',
+    required_fields: ['findings', 'sources', 'confidence', 'summary'],
+    optional_fields: [],
+    schema: {
+      findings: { type: 'string', description: 'Research findings and conclusions', validation: 'non-empty' },
+      sources: { type: 'string[]', description: 'List of sources referenced' },
+      confidence: { type: 'string', description: 'Confidence level (high|medium|low) with rationale', validation: 'non-empty' },
+      summary: { type: 'string', description: 'Brief summary of research', validation: 'non-empty' },
+    },
+  },
+  'reviewer': {
+    agent: 'reviewer',
+    required_fields: ['verdict', 'issues', 'summary'],
+    optional_fields: [],
+    schema: {
+      verdict: { type: 'string', description: 'Review verdict (pass|block|conditional)', validation: 'non-empty' },
+      issues: { type: 'string[]', description: 'List of issues found during review' },
+      summary: { type: 'string', description: 'Brief review summary', validation: 'non-empty' },
+    },
+  },
+  'documentation-writer': {
+    agent: 'documentation-writer',
+    required_fields: ['files_changed', 'summary'],
+    optional_fields: [],
+    schema: {
+      files_changed: { type: 'string[]', description: 'List of documentation file paths created or modified', validation: 'file-paths' },
+      summary: { type: 'string', description: 'Brief description of documentation changes', validation: 'non-empty' },
+    },
+  },
+  'copywriter': {
+    agent: 'copywriter',
+    required_fields: ['content', 'word_count', 'summary'],
+    optional_fields: [],
+    schema: {
+      content: { type: 'string', description: 'The written content or key excerpts', validation: 'non-empty' },
+      word_count: { type: 'number', description: 'Total word count of written content', validation: 'positive-int' },
+      summary: { type: 'string', description: 'Brief summary of content created', validation: 'non-empty' },
+    },
+  },
+  'performance-expert': {
+    agent: 'performance-expert',
+    required_fields: ['metrics_before', 'metrics_after', 'files_changed', 'summary'],
+    optional_fields: [],
+    schema: {
+      metrics_before: { type: 'object', description: 'Performance metrics before changes' },
+      metrics_after: { type: 'object', description: 'Performance metrics after changes' },
+      files_changed: { type: 'string[]', description: 'List of file paths created or modified', validation: 'file-paths' },
+      summary: { type: 'string', description: 'Summary of performance improvements', validation: 'non-empty' },
+    },
+  },
+  'database-engineer': {
+    agent: 'database-engineer',
+    required_fields: ['migrations', 'rls_policies', 'rollback_plan', 'summary'],
+    optional_fields: [],
+    schema: {
+      migrations: { type: 'string[]', description: 'List of migration file paths applied', validation: 'file-paths' },
+      rls_policies: { type: 'string[]', description: 'List of RLS policy names added or modified' },
+      rollback_plan: { type: 'string', description: 'Steps to roll back the changes if needed', validation: 'non-empty' },
+      summary: { type: 'string', description: 'Summary of database changes', validation: 'non-empty' },
+    },
+  },
+  'devops-expert': {
+    agent: 'devops-expert',
+    required_fields: ['files_changed', 'env_vars_added', 'summary'],
+    optional_fields: [],
+    schema: {
+      files_changed: { type: 'string[]', description: 'List of file paths created or modified', validation: 'file-paths' },
+      env_vars_added: { type: 'string[]', description: 'List of environment variable names added' },
+      summary: { type: 'string', description: 'Summary of DevOps changes', validation: 'non-empty' },
+    },
+  },
+  'api-designer': {
+    agent: 'api-designer',
+    required_fields: ['endpoints', 'schemas', 'summary'],
+    optional_fields: [],
+    schema: {
+      endpoints: { type: 'string[]', description: 'List of API endpoints designed or modified' },
+      schemas: { type: 'string[]', description: 'List of request/response schema names' },
+      summary: { type: 'string', description: 'Summary of API design decisions', validation: 'non-empty' },
+    },
+  },
+  'data-expert': {
+    agent: 'data-expert',
+    required_fields: ['pipeline_steps', 'files_changed', 'summary'],
+    optional_fields: [],
+    schema: {
+      pipeline_steps: { type: 'string[]', description: 'List of data pipeline steps implemented' },
+      files_changed: { type: 'string[]', description: 'List of file paths created or modified', validation: 'file-paths' },
+      summary: { type: 'string', description: 'Summary of data engineering work', validation: 'non-empty' },
+    },
+  },
+  'seo-specialist': {
+    agent: 'seo-specialist',
+    required_fields: ['files_changed', 'tags_added', 'summary'],
+    optional_fields: [],
+    schema: {
+      files_changed: { type: 'string[]', description: 'List of file paths created or modified', validation: 'file-paths' },
+      tags_added: { type: 'string[]', description: 'List of SEO tags or structured data items added' },
+      summary: { type: 'string', description: 'Summary of SEO changes', validation: 'non-empty' },
+    },
+  },
+  'release-manager': {
+    agent: 'release-manager',
+    required_fields: ['version', 'changelog_entries', 'checks_passed', 'summary'],
+    optional_fields: [],
+    schema: {
+      version: { type: 'string', description: 'The version string being released (e.g. 1.2.3)', validation: 'non-empty' },
+      changelog_entries: { type: 'string[]', description: 'List of changelog entries for this release' },
+      checks_passed: { type: 'boolean', description: 'Whether all release checks passed' },
+      summary: { type: 'string', description: 'Summary of the release', validation: 'non-empty' },
+    },
+  },
+}
+
+function applyValidation(
+  field: string,
+  value: unknown,
+  spec: FieldSpec,
+  missing: string[],
+): void {
+  if (spec.validation === 'non-empty') {
+    if (typeof value !== 'string' || value.trim() === '') {
+      missing.push(field)
+    }
+  } else if (spec.validation === 'file-paths') {
+    if (!Array.isArray(value) || !value.every(v => typeof v === 'string')) {
+      missing.push(field)
+    }
+  } else if (spec.validation === 'positive-int') {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      missing.push(field)
+    }
+  }
+}
+
+export function validateOutput(agent: string, output: string): ContractResult {
+  const contract = AGENT_CONTRACTS[agent.toLowerCase()]
+  if (!contract) {
+    return { valid: true, missing: [], warnings: ['no_contract_defined'] }
+  }
+
+  const blockMatch = output.match(/<!--\s*OUTPUT_CONTRACT\s*([\s\S]*?)-->/)
+  if (!blockMatch) {
+    return { valid: false, missing: ['__contract_block'], warnings: [] }
+  }
+
+  let data: Record<string, unknown>
+  try {
+    data = JSON.parse(blockMatch[1].trim()) as Record<string, unknown>
+  } catch {
+    return { valid: false, missing: ['__contract_block'], warnings: ['invalid_json'] }
+  }
+
+  const missing: string[] = []
+
+  for (const field of contract.required_fields) {
+    if (!(field in data) || data[field] === null || data[field] === undefined) {
+      missing.push(field)
+      continue
+    }
+    const fieldSpec = contract.schema[field]
+    if (fieldSpec?.validation) {
+      applyValidation(field, data[field], fieldSpec, missing)
+    }
+  }
+
+  return { valid: missing.length === 0, missing, warnings: [], data }
+}
+
+export function buildContractInstruction(agent: string): string | null {
+  const contract = AGENT_CONTRACTS[agent.toLowerCase()]
+  if (!contract) return null
+
+  const exampleFields = contract.required_fields
+    .map(f => {
+      const spec = contract.schema[f]
+      if (!spec) return `"${f}": "..."`
+      if (spec.type === 'string[]') return `"${f}": [...]`
+      if (spec.type === 'boolean') return `"${f}": true`
+      if (spec.type === 'number') return `"${f}": 0`
+      if (spec.type === 'object') return `"${f}": {}`
+      return `"${f}": "..."`
+    })
+    .join(', ')
+
+  return [
+    '## Output Contract (REQUIRED)',
+    'At the END of your response, include an OUTPUT_CONTRACT block:',
+    `<!-- OUTPUT_CONTRACT`,
+    `{ ${exampleFields} }`,
+    `-->`,
+    `The following fields are REQUIRED: ${contract.required_fields.join(', ')}`,
+  ].join('\n')
+}
+
+export function buildContractRetryPrompt(result: ContractResult): string {
+  return [
+    'Your previous output was missing the required OUTPUT_CONTRACT block.',
+    'At the END of your response, include:',
+    '<!-- OUTPUT_CONTRACT',
+    '{ ... }',
+    '-->',
+    `Missing fields: ${result.missing.join(', ')}`,
+  ].join('\n')
+}

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

@@ -0,0 +1,349 @@
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { createConvoyStore } from './store.js'
+import type { ConvoyStore } from './store.js'
+import {
+  extractExecutionHistory,
+  clusterConvoys,
+  analyzeAgentPerformance,
+  generateInsights,
+  analyzeDAG,
+  formatInsightsMarkdown,
+} from './dag-analysis.js'
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+let tmpDir: string
+let dbPath: string
+let store: ConvoyStore
+
+beforeEach(() => {
+  tmpDir = realpathSync(mkdtempSync(join(tmpdir(), 'dag-test-')))
+  dbPath = join(tmpDir, 'test.db')
+  store = createConvoyStore(dbPath)
+})
+
+afterEach(() => {
+  store.close()
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+type ConvoyInsert = Parameters<ConvoyStore['insertConvoy']>[0]
+type TaskInsert = Parameters<ConvoyStore['insertTask']>[0]
+
+function makeConvoy(overrides: Partial<ConvoyInsert> = {}): ConvoyInsert {
+  return {
+    id: 'convoy-1',
+    name: 'Test Convoy',
+    spec_hash: 'abc123',
+    status: 'pending',
+    branch: null,
+    created_at: new Date().toISOString(),
+    spec_yaml: 'name: test\nconcurrency: 2',
+    pipeline_id: null,
+    ...overrides,
+  }
+}
+
+function makeTask(overrides: Partial<TaskInsert> = {}): TaskInsert {
+  return {
+    id: 'task-1',
+    convoy_id: 'convoy-1',
+    phase: 0,
+    prompt: 'Do something',
+    agent: 'developer',
+    adapter: null,
+    model: null,
+    timeout_ms: 1_800_000,
+    status: 'pending',
+    retries: 0,
+    max_retries: 1,
+    files: null,
+    depends_on: null,
+    gates: null,
+    ...overrides,
+  } as TaskInsert
+}
+
+const NOW = new Date().toISOString()
+const LONG_AGO = new Date(Date.now() - 200 * 24 * 60 * 60 * 1000).toISOString()
+
+// ── extractExecutionHistory ───────────────────────────────────────────────────
+
+describe('extractExecutionHistory', () => {
+  it('returns empty arrays for an empty database', () => {
+    const result = extractExecutionHistory(store)
+    expect(result.convoys).toHaveLength(0)
+    expect(result.tasks).toHaveLength(0)
+  })
+
+  it('filters to only done/failed convoys', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'pending' }))
+    store.insertConvoy(makeConvoy({ id: 'c2', status: 'running' }))
+    store.insertConvoy(makeConvoy({ id: 'c3', status: 'done' }))
+    store.insertConvoy(makeConvoy({ id: 'c4', status: 'failed' }))
+    store.updateConvoyStatus('c3', 'done', { finished_at: NOW, started_at: NOW })
+    store.updateConvoyStatus('c4', 'failed', { finished_at: NOW, started_at: NOW })
+
+    const result = extractExecutionHistory(store)
+    const ids = result.convoys.map((c) => c.id)
+    expect(ids).toContain('c3')
+    expect(ids).toContain('c4')
+    expect(ids).not.toContain('c1')
+    expect(ids).not.toContain('c2')
+  })
+
+  it('respects sinceDays filter and excludes old convoys', () => {
+    store.insertConvoy(makeConvoy({ id: 'old', status: 'done' }))
+    store.updateConvoyStatus('old', 'done', { finished_at: LONG_AGO, started_at: LONG_AGO })
+
+    store.insertConvoy(makeConvoy({ id: 'recent', status: 'done' }))
+    store.updateConvoyStatus('recent', 'done', { finished_at: NOW, started_at: NOW })
+
+    const result = extractExecutionHistory(store, 90)
+    const ids = result.convoys.map((c) => c.id)
+    expect(ids).toContain('recent')
+    expect(ids).not.toContain('old')
+  })
+
+  it('includes tasks for matching convoys', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.updateConvoyStatus('c1', 'done', { finished_at: NOW, started_at: NOW })
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1' }))
+    store.insertTask(makeTask({ id: 't2', convoy_id: 'c1' }))
+
+    const result = extractExecutionHistory(store)
+    expect(result.tasks).toHaveLength(2)
+  })
+})
+
+// ── clusterConvoys ────────────────────────────────────────────────────────────
+
+describe('clusterConvoys', () => {
+  it('returns empty array for no convoys', () => {
+    expect(clusterConvoys([], [])).toHaveLength(0)
+  })
+
+  it('assigns correct bucket for small task count', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.updateConvoyStatus('c1', 'done', { finished_at: NOW, started_at: NOW })
+
+    const convoys = [store.getConvoy('c1')!]
+    const tasks = [makeTask({ id: 't1', convoy_id: 'c1' })]
+
+    const patterns = clusterConvoys(convoys, tasks as never)
+    expect(patterns).toHaveLength(1)
+    expect(patterns[0].name).toMatch(/^small/)
+  })
+
+  it('convoys with same agent set cluster together', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.updateConvoyStatus('c1', 'done', { finished_at: NOW, started_at: NOW })
+    store.insertConvoy(makeConvoy({ id: 'c2', status: 'done' }))
+    store.updateConvoyStatus('c2', 'done', { finished_at: NOW, started_at: NOW })
+
+    const convoys = [store.getConvoy('c1')!, store.getConvoy('c2')!]
+    const tasks = [
+      makeTask({ id: 't1', convoy_id: 'c1', agent: 'developer' }),
+      makeTask({ id: 't2', convoy_id: 'c2', agent: 'developer' }),
+    ]
+
+    const patterns = clusterConvoys(convoys, tasks as never)
+    expect(patterns).toHaveLength(1)
+    expect(patterns[0].sample_size).toBe(2)
+  })
+
+  it('calculates success rate correctly', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.updateConvoyStatus('c1', 'done', { finished_at: NOW, started_at: NOW })
+    store.insertConvoy(makeConvoy({ id: 'c2', status: 'failed' }))
+    store.updateConvoyStatus('c2', 'failed', { finished_at: NOW, started_at: NOW })
+
+    const convoys = [store.getConvoy('c1')!, store.getConvoy('c2')!]
+    const tasks = [
+      makeTask({ id: 't1', convoy_id: 'c1', agent: 'developer' }),
+      makeTask({ id: 't2', convoy_id: 'c2', agent: 'developer' }),
+    ]
+
+    const patterns = clusterConvoys(convoys, tasks as never)
+    expect(patterns).toHaveLength(1)
+    expect(patterns[0].success_rate).toBe(0.5)
+  })
+})
+
+// ── analyzeAgentPerformance ───────────────────────────────────────────────────
+
+describe('analyzeAgentPerformance', () => {
+  it('returns empty array for no tasks', () => {
+    expect(analyzeAgentPerformance([])).toHaveLength(0)
+  })
+
+  it('computes correct success rate for mixed tasks', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1', status: 'done', agent: 'developer' }))
+    store.insertTask(makeTask({ id: 't2', convoy_id: 'c1', status: 'done', agent: 'developer' }))
+    store.insertTask(makeTask({ id: 't3', convoy_id: 'c1', status: 'failed', agent: 'developer' }))
+    store.updateTaskStatus('t1', 'c1', 'done')
+    store.updateTaskStatus('t2', 'c1', 'done')
+    store.updateTaskStatus('t3', 'c1', 'failed')
+
+    const tasks = store.getTasksByConvoy('c1')
+    const result = analyzeAgentPerformance(tasks)
+    expect(result).toHaveLength(1)
+    expect(result[0].success_rate).toBeCloseTo(2 / 3)
+    expect(result[0].total_tasks).toBe(3)
+  })
+
+  it('identifies best file patterns', () => {
+    const files = JSON.stringify(['src/cli/convoy/engine.ts', 'src/cli/convoy/store.ts'])
+    store.insertConvoy(makeConvoy({ id: 'c1' }))
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1', status: 'done', agent: 'developer', files }))
+    store.insertTask(makeTask({ id: 't2', convoy_id: 'c1', status: 'done', agent: 'developer', files }))
+    store.insertTask(makeTask({ id: 't3', convoy_id: 'c1', status: 'done', agent: 'developer', files }))
+    store.updateTaskStatus('t1', 'c1', 'done')
+    store.updateTaskStatus('t2', 'c1', 'done')
+    store.updateTaskStatus('t3', 'c1', 'done')
+
+    const tasks = store.getTasksByConvoy('c1')
+    const result = analyzeAgentPerformance(tasks)
+    expect(result[0].best_file_patterns).toContain('src/cli')
+  })
+
+  it('identifies worst file patterns for low success rate', () => {
+    const files = JSON.stringify(['src/dashboard/page.ts', 'src/dashboard/layout.ts'])
+    store.insertConvoy(makeConvoy({ id: 'c1' }))
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1', status: 'failed', agent: 'developer', files }))
+    store.insertTask(makeTask({ id: 't2', convoy_id: 'c1', status: 'failed', agent: 'developer', files }))
+    store.insertTask(makeTask({ id: 't3', convoy_id: 'c1', status: 'failed', agent: 'developer', files }))
+    store.updateTaskStatus('t1', 'c1', 'failed')
+    store.updateTaskStatus('t2', 'c1', 'failed')
+    store.updateTaskStatus('t3', 'c1', 'failed')
+
+    const tasks = store.getTasksByConvoy('c1')
+    const result = analyzeAgentPerformance(tasks)
+    expect(result[0].worst_file_patterns).toContain('src/dashboard')
+  })
+
+  it('returns avg_duration_ms of 0 when no tasks have timestamps', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1' }))
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1', status: 'done', agent: 'developer' }))
+
+    const tasks = store.getTasksByConvoy('c1')
+    const result = analyzeAgentPerformance(tasks)
+    expect(result[0].avg_duration_ms).toBe(0)
+  })
+})
+
+// ── generateInsights ──────────────────────────────────────────────────────────
+
+describe('generateInsights', () => {
+  it('returns no-data message for empty inputs', () => {
+    const insights = generateInsights([], [])
+    expect(insights).toHaveLength(1)
+    expect(insights[0]).toMatch(/No execution history/)
+  })
+
+  it('produces warning for low success rate agent', () => {
+    const agents = [
+      {
+        agent: 'developer',
+        total_tasks: 10,
+        success_rate: 0.5,
+        avg_duration_ms: 0,
+        avg_tokens: 0,
+        avg_retries: 0,
+        best_file_patterns: [],
+        worst_file_patterns: [],
+      },
+    ]
+    const insights = generateInsights([], agents)
+    expect(insights.some((i) => i.includes('⚠️') && i.includes('developer'))).toBe(true)
+    expect(insights.some((i) => i.includes('50%'))).toBe(true)
+  })
+
+  it('produces 100% success message for perfect agent with enough tasks', () => {
+    const agents = [
+      {
+        agent: 'testing-expert',
+        total_tasks: 5,
+        success_rate: 1,
+        avg_duration_ms: 0,
+        avg_tokens: 0,
+        avg_retries: 0,
+        best_file_patterns: [],
+        worst_file_patterns: [],
+      },
+    ]
+    const insights = generateInsights([], agents)
+    expect(insights.some((i) => i.includes('100%') && i.includes('testing-expert'))).toBe(true)
+  })
+
+  it('includes pattern insight with concurrency', () => {
+    const patterns = [
+      {
+        name: 'small-developer',
+        task_count_range: [1, 2] as [number, number],
+        agent_sequence: ['developer'],
+        avg_duration_ms: 120000,
+        avg_tokens: 5000,
+        success_rate: 0.9,
+        common_failure_agents: [],
+        recommended_concurrency: 2,
+        sample_size: 5,
+      },
+    ]
+    const insights = generateInsights(patterns, [])
+    expect(insights.some((i) => i.includes('concurrency 2'))).toBe(true)
+  })
+})
+
+// ── analyzeDAG ────────────────────────────────────────────────────────────────
+
+describe('analyzeDAG', () => {
+  it('returns valid structure for empty database (no crash)', () => {
+    const result = analyzeDAG(store)
+    expect(result).toHaveProperty('patterns')
+    expect(result).toHaveProperty('agent_stats')
+    expect(result).toHaveProperty('insights')
+    expect(result).toHaveProperty('generated_at')
+    expect(Array.isArray(result.patterns)).toBe(true)
+    expect(Array.isArray(result.agent_stats)).toBe(true)
+    expect(Array.isArray(result.insights)).toBe(true)
+  })
+
+  it('returns populated agent data when history exists', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.updateConvoyStatus('c1', 'done', { finished_at: NOW, started_at: NOW })
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1', status: 'done', agent: 'developer' }))
+    store.updateTaskStatus('t1', 'c1', 'done', { finished_at: NOW, started_at: NOW, total_tokens: 5000 })
+
+    const result = analyzeDAG(store)
+    expect(result.agent_stats.length).toBeGreaterThan(0)
+    expect(result.agent_stats[0].agent).toBe('developer')
+  })
+})
+
+// ── formatInsightsMarkdown ────────────────────────────────────────────────────
+
+describe('formatInsightsMarkdown', () => {
+  it('contains expected section headers', () => {
+    const rec = analyzeDAG(store)
+    const md = formatInsightsMarkdown(rec)
+    expect(md).toContain('## Convoy Patterns')
+    expect(md).toContain('## Agent Performance')
+    expect(md).toContain('## Recommendations')
+  })
+
+  it('includes agent table for populated data', () => {
+    store.insertConvoy(makeConvoy({ id: 'c1', status: 'done' }))
+    store.updateConvoyStatus('c1', 'done', { finished_at: NOW, started_at: NOW })
+    store.insertTask(makeTask({ id: 't1', convoy_id: 'c1', status: 'done', agent: 'developer' }))
+    store.updateTaskStatus('t1', 'c1', 'done', { finished_at: NOW, started_at: NOW, total_tokens: 5000 })
+
+    const rec = analyzeDAG(store)
+    const md = formatInsightsMarkdown(rec)
+    expect(md).toContain('developer')
+  })
+})