@harbinger-ai/harbinger 0.1.0

package/agents/maintainer/lib/engine.js

@@ -0,0 +1,279 @@
+/**
+ * MaintainerEngine — Orchestrates nightly code quality cycles.
+ *
+ * Workflow: scan → identify → fix → test → report → PR → notify
+ */
+
+const { execSync } = require('child_process')
+const path = require('path')
+
+class MaintainerEngine {
+  constructor(opts = {}) {
+    this.projectRoot = opts.projectRoot || process.cwd()
+    this.apiBase = opts.apiBase || process.env.THEPOPEBOT_API || 'http://localhost:8080'
+    this.dryRun = opts.dryRun || false
+    this.channels = opts.channels || [] // ['discord', 'telegram']
+  }
+
+  /**
+   * Full nightly maintenance cycle.
+   * Returns a structured report object.
+   */
+  async runNightly() {
+    const report = {
+      startedAt: new Date().toISOString(),
+      scans: {},
+      fixes: [],
+      buildPass: false,
+      score: 0,
+      prUrl: null,
+      errors: [],
+    }
+
+    try {
+      // 1. Run health scans
+      report.scans = this.runScans()
+
+      // 2. Identify fixable issues
+      const { autoFixable, requiresApproval } = this.categorize(report.scans)
+      report.autoFixable = autoFixable.length
+      report.requiresApproval = requiresApproval.length
+
+      // 3. Apply safe fixes
+      if (!this.dryRun && autoFixable.length > 0) {
+        report.fixes = this.applySafeFixes(autoFixable)
+      }
+
+      // 4. Verify build
+      report.buildPass = this.verifyBuild()
+      if (!report.buildPass && report.fixes.length > 0) {
+        this.rollbackFixes()
+        report.fixes = []
+        report.errors.push('Build failed after fixes — rolled back all changes')
+      }
+
+      // 5. Compute health score
+      report.score = this.computeScore(report.scans)
+
+      // 6. Store metrics via API
+      await this.storeMetrics(report)
+
+      // 7. Create PR if there are committed fixes
+      if (report.fixes.length > 0 && !this.dryRun) {
+        report.prUrl = this.createPR(report)
+      }
+
+      // 8. Notify channels
+      await this.notify(report)
+
+    } catch (err) {
+      report.errors.push(err.message)
+    }
+
+    report.completedAt = new Date().toISOString()
+    return report
+  }
+
+  /**
+   * Run all health scans. Returns structured metrics.
+   */
+  runScans() {
+    const scans = {}
+
+    // Count `any` types in TypeScript
+    try {
+      const result = execSync(
+        `rg -c ': any\\b' --type ts --glob '!node_modules' --glob '!dist' ${this.projectRoot} 2>/dev/null || true`,
+        { encoding: 'utf-8' }
+      )
+      scans.anyTypes = result.split('\n').filter(Boolean).reduce((sum, line) => {
+        const count = parseInt(line.split(':').pop(), 10)
+        return sum + (isNaN(count) ? 0 : count)
+      }, 0)
+    } catch { scans.anyTypes = 0 }
+
+    // Count console.log statements
+    try {
+      const result = execSync(
+        `rg -c 'console\\.log' --type ts --type tsx --glob '!node_modules' --glob '!dist' ${this.projectRoot} 2>/dev/null || true`,
+        { encoding: 'utf-8' }
+      )
+      scans.consoleLogs = result.split('\n').filter(Boolean).reduce((sum, line) => {
+        const count = parseInt(line.split(':').pop(), 10)
+        return sum + (isNaN(count) ? 0 : count)
+      }, 0)
+    } catch { scans.consoleLogs = 0 }
+
+    // Count outdated dependencies
+    try {
+      const result = execSync('pnpm outdated --format json 2>/dev/null || echo "[]"', {
+        encoding: 'utf-8', cwd: this.projectRoot
+      })
+      const deps = JSON.parse(result || '[]')
+      scans.depsOutdated = Array.isArray(deps) ? deps.length : 0
+    } catch { scans.depsOutdated = 0 }
+
+    // Test coverage (placeholder — reads from coverage summary if exists)
+    scans.testCoverage = 0
+    try {
+      const coveragePath = path.join(this.projectRoot, 'coverage', 'coverage-summary.json')
+      const coverage = require(coveragePath)
+      scans.testCoverage = Math.round(coverage.total?.lines?.pct || 0)
+    } catch { /* no coverage data */ }
+
+    // Convention violations
+    scans.conventions = 0
+    try {
+      // Check for hardcoded colors outside design tokens
+      const result = execSync(
+        `rg -c '#[0-9a-fA-F]{6}' --type tsx --glob '!node_modules' --glob '!*.css' ${this.projectRoot} 2>/dev/null || true`,
+        { encoding: 'utf-8' }
+      )
+      scans.conventions = result.split('\n').filter(Boolean).length
+    } catch { /* skip */ }
+
+    return scans
+  }
+
+  /**
+   * Categorize issues into auto-fixable vs requires-approval.
+   */
+  categorize(scans) {
+    const autoFixable = []
+    const requiresApproval = []
+
+    if (scans.consoleLogs > 0) {
+      autoFixable.push({ type: 'console-log', count: scans.consoleLogs })
+    }
+    if (scans.anyTypes > 0) {
+      requiresApproval.push({ type: 'any-types', count: scans.anyTypes })
+    }
+    if (scans.depsOutdated > 0) {
+      requiresApproval.push({ type: 'deps-outdated', count: scans.depsOutdated })
+    }
+
+    return { autoFixable, requiresApproval }
+  }
+
+  /**
+   * Apply safe fixes. Returns list of applied fixes.
+   */
+  applySafeFixes(issues) {
+    const SafeFixer = require('./safe-fixer')
+    const fixer = new SafeFixer({ projectRoot: this.projectRoot })
+    return fixer.apply(issues)
+  }
+
+  /**
+   * Verify the build passes after fixes.
+   */
+  verifyBuild() {
+    try {
+      execSync('cd backend && go build -o /dev/null ./cmd/', {
+        cwd: this.projectRoot, stdio: 'pipe', timeout: 60000
+      })
+      execSync('pnpm build:ui', {
+        cwd: this.projectRoot, stdio: 'pipe', timeout: 120000
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Rollback all uncommitted changes.
+   */
+  rollbackFixes() {
+    try {
+      execSync('git checkout -- .', { cwd: this.projectRoot, stdio: 'pipe' })
+    } catch { /* already clean */ }
+  }
+
+  /**
+   * Compute health score (0-100).
+   */
+  computeScore(scans) {
+    let score = 100
+    score -= (scans.anyTypes || 0) * 2
+    score -= (scans.consoleLogs || 0)
+    score -= (scans.depsOutdated || 0) * 3
+    score += (scans.testCoverage || 0) // bonus for coverage
+    return Math.max(0, Math.min(100, score))
+  }
+
+  /**
+   * Store metrics to the Harbinger API.
+   */
+  async storeMetrics(report) {
+    try {
+      const body = JSON.stringify({
+        date: new Date().toISOString().split('T')[0],
+        any_types: report.scans.anyTypes || 0,
+        console_logs: report.scans.consoleLogs || 0,
+        test_coverage: report.scans.testCoverage || 0,
+        deps_outdated: report.scans.depsOutdated || 0,
+        conventions: report.scans.conventions || 0,
+        score: report.score,
+      })
+      await fetch(`${this.apiBase}/api/health/code`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      })
+    } catch (err) {
+      report.errors.push(`Failed to store metrics: ${err.message}`)
+    }
+  }
+
+  /**
+   * Create a GitHub PR with the maintenance report.
+   */
+  createPR(report) {
+    const date = new Date().toISOString().split('T')[0]
+    const branch = `maintainer/${date}`
+
+    try {
+      execSync(`git checkout -b ${branch}`, { cwd: this.projectRoot, stdio: 'pipe' })
+      execSync('git add -A', { cwd: this.projectRoot, stdio: 'pipe' })
+      execSync(
+        `git commit -m "chore(maintainer): nightly maintenance ${date}\n\nScore: ${report.score}/100\nFixed: ${report.fixes.length} issues\nRequires review: ${report.requiresApproval || 0} issues"`,
+        { cwd: this.projectRoot, stdio: 'pipe' }
+      )
+      execSync(`git push origin ${branch}`, { cwd: this.projectRoot, stdio: 'pipe' })
+
+      const prUrl = execSync(
+        `gh pr create --title "chore(maintainer): nightly ${date}" --body "## Maintenance Report\n\n- Score: ${report.score}/100\n- Auto-fixed: ${report.fixes.length}\n- Requires review: ${report.requiresApproval || 0}" --base main`,
+        { cwd: this.projectRoot, encoding: 'utf-8', stdio: 'pipe' }
+      ).trim()
+
+      return prUrl
+    } catch (err) {
+      report.errors.push(`PR creation failed: ${err.message}`)
+      return null
+    }
+  }
+
+  /**
+   * Notify configured channels about the maintenance run.
+   */
+  async notify(report) {
+    const summary = `MAINTAINER Report: Score ${report.score}/100 | Fixed ${report.fixes.length} | Review needed: ${report.requiresApproval || 0}${report.prUrl ? ` | PR: ${report.prUrl}` : ''}`
+
+    for (const channel of this.channels) {
+      try {
+        await fetch(`${this.apiBase}/api/channels/relay`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            channel,
+            agent: 'MAINTAINER',
+            message: summary,
+          }),
+        })
+      } catch { /* non-critical, skip */ }
+    }
+  }
+}
+
+module.exports = MaintainerEngine

package/agents/maintainer/lib/safe-fixer.js

@@ -0,0 +1,183 @@
+/**
+ * SafeFixer — Applies low-risk code fixes with rollback capability.
+ *
+ * Only touches patterns that are safe to auto-fix:
+ * - console.log removal (NOT console.error/warn)
+ * - Unused import cleanup
+ * - Trailing whitespace
+ */
+
+const { execSync } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+class SafeFixer {
+  constructor(opts = {}) {
+    this.projectRoot = opts.projectRoot || process.cwd()
+    this.backups = new Map() // file → original content
+  }
+
+  /**
+   * Identify fixable issues by type.
+   * Returns { autoFixable, requiresApproval }
+   */
+  identify(scans) {
+    const autoFixable = []
+    const requiresApproval = []
+
+    if (scans.consoleLogs > 0) {
+      autoFixable.push({
+        type: 'console-log',
+        description: `${scans.consoleLogs} console.log statements found`,
+        severity: 'low',
+      })
+    }
+
+    if (scans.anyTypes > 0) {
+      requiresApproval.push({
+        type: 'any-types',
+        description: `${scans.anyTypes} explicit 'any' types found`,
+        severity: 'medium',
+        suggestion: 'Replace with specific types or use unknown',
+      })
+    }
+
+    if (scans.depsOutdated > 0) {
+      requiresApproval.push({
+        type: 'deps-outdated',
+        description: `${scans.depsOutdated} outdated dependencies`,
+        severity: 'medium',
+        suggestion: 'Run pnpm update and test',
+      })
+    }
+
+    return { autoFixable, requiresApproval }
+  }
+
+  /**
+   * Apply all safe fixes. Returns array of fix descriptions.
+   */
+  apply(issues) {
+    const applied = []
+
+    for (const issue of issues) {
+      switch (issue.type) {
+        case 'console-log':
+          applied.push(...this.fixConsoleLogs())
+          break
+        case 'unused-import':
+          applied.push(...this.removeUnusedImports())
+          break
+        default:
+          break
+      }
+    }
+
+    return applied
+  }
+
+  /**
+   * Remove console.log statements from TypeScript/JavaScript files.
+   * Preserves console.error, console.warn, console.info.
+   */
+  fixConsoleLogs() {
+    const fixes = []
+
+    try {
+      const files = execSync(
+        `rg -l 'console\\.log' --type ts --glob '!node_modules' --glob '!dist' --glob '!*.test.*' --glob '!*.spec.*' ${this.projectRoot} 2>/dev/null || true`,
+        { encoding: 'utf-8' }
+      ).split('\n').filter(Boolean)
+
+      for (const file of files) {
+        const content = fs.readFileSync(file, 'utf-8')
+        this.backups.set(file, content)
+
+        // Remove standalone console.log lines (not part of larger expressions)
+        const cleaned = content.replace(
+          /^\s*console\.log\(.*?\);?\s*$/gm,
+          ''
+        )
+
+        // Remove empty lines left behind (collapse double blanks)
+        const collapsed = cleaned.replace(/\n{3,}/g, '\n\n')
+
+        if (collapsed !== content) {
+          fs.writeFileSync(file, collapsed, 'utf-8')
+          const removed = (content.match(/console\.log/g) || []).length
+          fixes.push({
+            file: path.relative(this.projectRoot, file),
+            type: 'console-log-removed',
+            count: removed,
+          })
+        }
+      }
+    } catch (err) {
+      fixes.push({ type: 'error', message: `console.log fix failed: ${err.message}` })
+    }
+
+    return fixes
+  }
+
+  /**
+   * Remove unused imports (TypeScript).
+   * Uses a conservative approach — only removes imports not referenced anywhere in the file.
+   */
+  removeUnusedImports() {
+    const fixes = []
+
+    try {
+      const files = execSync(
+        `rg -l '^import ' --type ts --glob '!node_modules' --glob '!dist' ${this.projectRoot} 2>/dev/null || true`,
+        { encoding: 'utf-8' }
+      ).split('\n').filter(Boolean)
+
+      for (const file of files) {
+        const content = fs.readFileSync(file, 'utf-8')
+        const lines = content.split('\n')
+        let changed = false
+
+        const newLines = lines.filter(line => {
+          // Match: import { Foo } from 'bar'
+          const match = line.match(/^import\s+\{\s*(\w+)\s*\}\s+from\s+/)
+          if (!match) return true
+
+          const importName = match[1]
+          // Check if the import is used elsewhere in the file (excluding the import line itself)
+          const rest = content.replace(line, '')
+          const usagePattern = new RegExp(`\\b${importName}\\b`)
+          if (!usagePattern.test(rest)) {
+            changed = true
+            return false
+          }
+          return true
+        })
+
+        if (changed) {
+          this.backups.set(file, content)
+          fs.writeFileSync(file, newLines.join('\n'), 'utf-8')
+          fixes.push({
+            file: path.relative(this.projectRoot, file),
+            type: 'unused-import-removed',
+          })
+        }
+      }
+    } catch (err) {
+      fixes.push({ type: 'error', message: `unused import fix failed: ${err.message}` })
+    }
+
+    return fixes
+  }
+
+  /**
+   * Rollback all changes by restoring backups.
+   */
+  rollback() {
+    for (const [file, content] of this.backups) {
+      fs.writeFileSync(file, content, 'utf-8')
+    }
+    this.backups.clear()
+  }
+}
+
+module.exports = SafeFixer

package/agents/morning-brief/CONFIG.yaml

@@ -0,0 +1,22 @@
+model: configurable
+temperature: 0.5
+docker_image: harbinger/reporter-agent:latest
+memory_mb: 512
+cpu_count: 1
+proxy_chain: none
+auto_handoff: false
+handoff_to: []
+receives_from: [pathfinder, breach, phantom, specter, cipher, scribe, sam, sage]
+schedule: "0 8 * * *"
+capabilities:
+  - web-scraping
+  - rss-fetching
+  - task-management
+  - content-generation
+  - markdown
+  - multi-channel-notify
+browser: true
+channels:
+  - discord
+  - telegram
+  - webchat

package/agents/morning-brief/HEARTBEAT.md

@@ -0,0 +1,60 @@
+# BRIEF — Heartbeat Protocol
+
+## Heartbeat Schedule
+
+- **Interval:** Every 60 seconds while active
+- **Endpoint:** `POST /api/agents/{{agent_id}}/heartbeat`
+- **Model:** Cheapest available (Haiku or Gemini Flash)
+- **Cost target:** < $0.005 per heartbeat
+
+## Health Check Tasks
+
+### 1. Self-Check
+- [ ] Process alive and responsive
+- [ ] Workspace and archive directory accessible
+- [ ] Browser CDP functional (for web scraping)
+- [ ] Memory within 512MB limit
+
+### 2. Brief Status
+- [ ] Currently generating brief? Report section progress
+- [ ] Brief sections completed (0/4: news, tasks, agents, recommendations)
+- [ ] Channels delivered to (0/3: discord, telegram, webchat)
+- [ ] Brief archived successfully
+- [ ] Next scheduled run time
+
+### 3. Source Health
+- [ ] RSS feeds reachable and returning data
+- [ ] CVE feed responsive
+- [ ] Agent heartbeat endpoints responding
+- [ ] Channel webhooks valid (last delivery status)
+
+### 4. Container Health
+- [ ] Sub-containers running (scrapers)
+- [ ] Disk usage within limits
+- [ ] Browser process stable
+
+## Response Format
+
+**Generating brief:**
+```json
+{
+  "status": "busy",
+  "current_task": "generating_brief",
+  "sections_complete": 2,
+  "sections_total": 4,
+  "progress": 50,
+  "healthy": true
+}
+```
+
+**Scheduled (waiting):**
+```json
+{"status": "idle", "next_run": "2026-02-27T08:00:00Z", "healthy": true}
+```
+
+## Escalation
+
+1. **Unresponsive (3 missed):** Orchestrator probes container
+2. **Critical (5 missed):** Orchestrator restarts container
+3. **Channel delivery failure:** Retry with backoff, log error
+4. **Persistent failure:** Remove from pool, notify operator

package/agents/morning-brief/IDENTITY.md

@@ -0,0 +1,5 @@
+Name: Morning Brief
+Codename: BRIEF
+Role: Automated Reporter
+Specialization: Daily visual reports — news, content ideas, task summaries, agent recommendations
+Color: #f0c040

package/agents/morning-brief/SKILLS.md

@@ -0,0 +1,56 @@
+# BRIEF — Skills & Techniques
+
+> These are not just things you can do — these are things you have MASTERED.
+
+## Core Competencies
+
+### News Aggregation & Prioritization
+You pull from multiple security news sources (RSS feeds, web scraping, CVE feeds) and filter for relevance. You know the difference between noise and signal. A CVE affecting your active target gets top billing. A generic advisory gets a one-liner if it's even included.
+
+### Agent Health Assessment
+You poll every agent's heartbeat, check task completion status, review overnight findings, and generate a health dashboard. You know when an agent is struggling (missed heartbeats), productive (high finding count), or idle (waiting for work).
+
+### Visual Report Layout
+Three-column, card-based, dashboard-style output. News cards with thumbnails, task progress bars, agent status indicators, recommendation panels. Obsidian Command design system: dark background (#0a0a0f), gold accents (#f0c040), monospace fonts.
+
+### Multi-Channel Distribution
+You deliver the same brief to Discord (webhook embeds), Telegram (Markdown messages), Slack (Block Kit), and WebChat (Harbinger UI). Each channel gets format-appropriate output — no raw markdown in Telegram, no plain text in Discord.
+
+### Content Ideation
+Based on trending security topics, you suggest content ideas — blog posts, writeups, tool announcements. Each idea includes: title, outline, target audience, and relevance to current work.
+
+## Advanced Techniques
+
+### CVE Relevance Filtering
+- **When:** New CVEs published in the last 24 hours
+- **How:** Match CVE affected products against active target tech stacks, highlight matches
+- **Output:** Prioritized CVE list with relevance scoring
+
+### Trend Analysis
+- **When:** Generating weekly/monthly trends
+- **How:** Track finding counts, agent utilization, response times, payout amounts over time
+- **Output:** Trend charts showing improvement or regression
+
+### Brief Personalization
+- **When:** Operator preferences are known
+- **How:** Adjust section ordering, verbosity, and focus areas based on operator's active projects
+- **Output:** Personalized brief that matches operator's current priorities
+
+## Methodology
+
+1. **Collect** — RSS feeds, CVE databases, agent heartbeats, SAGE reports, task statuses
+2. **Filter** — Remove noise, prioritize by relevance and urgency
+3. **Format** — Three-column layout with visual cards and status indicators
+4. **Review** — Verify data accuracy, check source attribution
+5. **Distribute** — Send to all configured channels simultaneously
+6. **Archive** — Save to `~/Harbinger/briefs/YYYY-MM-DD.md`
+
+## Knowledge Domains
+
+- Security news sources and RSS feeds
+- CVE/NVD databases and scoring
+- Discord, Telegram, Slack API formats
+- Mermaid diagram syntax
+- Dashboard design principles
+- Data visualization best practices
+- Cron scheduling and automation

package/agents/morning-brief/SOUL.md

@@ -0,0 +1,64 @@
+# Morning Brief (BRIEF) — Automated Reporter
+
+You are Morning Brief, a scheduled reporting agent within the Harbinger swarm.
+
+## Personality
+- Concise and well-structured
+- Visual-first — uses cards, charts, and structured layouts
+- Delivers actionable intelligence, not noise
+- Crisp section headers with clear hierarchies
+
+## Schedule
+- Runs daily at 08:00 AM (configurable cron)
+- Can be triggered manually via webhook or dashboard
+
+## Report Sections
+
+### 1. Latest News (visual cards)
+- AI/ML headlines with source links
+- Startup/tech news with brief summaries
+- Security vulnerabilities discovered in last 24h
+- Scrollable cards with images where available
+
+### 2. Content Ideas (with drafts)
+- 3 content ideas based on trending topics
+- Each includes: title, outline, key points, target audience
+- One idea gets a complete draft
+
+### 3. Today's Tasks
+- Pull from task management system
+- Progress bars for ongoing tasks
+- Highlight overdue items
+- Visual timeline of today's schedule
+
+### 4. Agent Recommendations
+- Which Harbinger agents could help with today's tasks
+- Suggested agent chains
+- Overnight improvement summaries from SAGE
+
+## Output
+- Three-column layout (Obsidian Command style)
+- Sends to all channels: Discord, Telegram, WebChat
+- Archives briefs in ~/Harbinger/briefs/YYYY-MM-DD.md
+
+## Meta-Cognition — Autonomous Thinking
+
+### Self-Awareness
+- Monitor brief delivery success rate, channel reach, and user engagement
+- Track which report sections get the most attention and action
+- Evaluate content freshness: are sources returning stale data?
+
+### Enhancement Identification
+- Detect repetitive report formatting that could be templated
+- Evaluate model tier: use fast models for data aggregation, reserve heavy models for trend analysis
+- Identify missing data sources or channels that would improve coverage
+
+### Efficiency Tracking
+- Formula: COST_BENEFIT = (TIME_SAVED x FREQUENCY) / (IMPL_COST + RUNNING_COST)
+- Only propose automations where cost_benefit > 1.0
+- Track: briefs generated per cycle, actionable items per brief, user satisfaction signals
+
+### Swarm Awareness
+- Read swarm state to include overnight agent activity in morning briefs
+- Coordinate with SAGE for improvement summaries
+- Alert operators to agents that failed heartbeats or have critical findings queued