@harbinger-ai/harbinger 0.1.0

package/lib/tools/github.js

@@ -0,0 +1,217 @@
+/**
+ * GitHub REST API helper with authentication
+ * @param {string} endpoint - API endpoint (e.g., '/repos/owner/repo/...')
+ * @param {object} options - Fetch options (method, body, headers)
+ * @returns {Promise<object>} - Parsed JSON response
+ */
+async function githubApi(endpoint, options = {}) {
+  const { GH_TOKEN } = process.env;
+  if (!GH_TOKEN) throw new Error('GH_TOKEN environment variable is required for GitHub API calls');
+  const res = await fetch(`https://api.github.com${endpoint}`, {
+    ...options,
+    headers: {
+      'Authorization': `Bearer ${GH_TOKEN}`,
+      'Accept': 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      ...options.headers,
+    },
+  });
+
+  if (!res.ok) {
+    const error = await res.text();
+    throw new Error(`GitHub API error: ${res.status} ${error}`);
+  }
+
+  return res.json();
+}
+
+/**
+ * Get workflow runs with optional status and workflow filter
+ * @param {string} [status] - Filter by status (in_progress, queued, completed)
+ * @param {string} [workflow] - Workflow filename to scope to (e.g., 'run-job.yml')
+ * @returns {Promise<object>} - Workflow runs response
+ */
+async function getWorkflowRuns(status, { workflow, page = 1, perPage = 100 } = {}) {
+  const { GH_OWNER, GH_REPO } = process.env;
+  const params = new URLSearchParams();
+  if (status) params.set('status', status);
+  params.set('per_page', String(perPage));
+  params.set('page', String(page));
+
+  const query = params.toString();
+  const path = workflow
+    ? `/repos/${GH_OWNER}/${GH_REPO}/actions/workflows/${workflow}/runs?${query}`
+    : `/repos/${GH_OWNER}/${GH_REPO}/actions/runs?${query}`;
+  return githubApi(path);
+}
+
+/**
+ * Get jobs for a specific workflow run
+ * @param {number} runId - Workflow run ID
+ * @returns {Promise<object>} - Jobs response with steps
+ */
+async function getWorkflowRunJobs(runId) {
+  const { GH_OWNER, GH_REPO } = process.env;
+  return githubApi(`/repos/${GH_OWNER}/${GH_REPO}/actions/runs/${runId}/jobs`);
+}
+
+/**
+ * Get job status for running/recent jobs
+ * @param {string} [jobId] - Optional specific job ID to filter by
+ * @returns {Promise<object>} - Status summary with jobs array
+ */
+async function getJobStatus(jobId) {
+  // Fetch both in_progress and queued runs (scoped to run-job.yml)
+  const [inProgress, queued] = await Promise.all([
+    getWorkflowRuns('in_progress', { workflow: 'run-job.yml' }),
+    getWorkflowRuns('queued', { workflow: 'run-job.yml' }),
+  ]);
+
+  const allRuns = [...(inProgress.workflow_runs || []), ...(queued.workflow_runs || [])];
+
+  // Filter to only job/* branches
+  const jobRuns = allRuns.filter(run => run.head_branch?.startsWith('job/'));
+
+  // If specific job requested, filter further
+  const filteredRuns = jobId
+    ? jobRuns.filter(run => run.head_branch === `job/${jobId}`)
+    : jobRuns;
+
+  // Get detailed job info for each run
+  const jobs = await Promise.all(
+    filteredRuns.map(async (run) => {
+      const extractedJobId = run.head_branch.slice(4); // Remove 'job/' prefix
+      const startedAt = new Date(run.created_at);
+      const durationMinutes = Math.round((Date.now() - startedAt.getTime()) / 60000);
+
+      let currentStep = null;
+      let stepsCompleted = 0;
+      let stepsTotal = 0;
+
+      try {
+        const jobsData = await getWorkflowRunJobs(run.id);
+        if (jobsData.jobs?.length > 0) {
+          const job = jobsData.jobs[0];
+          stepsTotal = job.steps?.length || 0;
+          stepsCompleted = job.steps?.filter(s => s.status === 'completed').length || 0;
+          currentStep = job.steps?.find(s => s.status === 'in_progress')?.name || null;
+        }
+      } catch (err) {
+        // Jobs endpoint may fail if run hasn't started yet
+      }
+
+      return {
+        job_id: extractedJobId,
+        branch: run.head_branch,
+        status: run.status,
+        started_at: run.created_at,
+        duration_minutes: durationMinutes,
+        current_step: currentStep,
+        steps_completed: stepsCompleted,
+        steps_total: stepsTotal,
+        run_id: run.id,
+      };
+    })
+  );
+
+  // Count only job/* branches, not all workflows
+  const runningCount = jobs.filter(j => j.status === 'in_progress').length;
+  const queuedCount = jobs.filter(j => j.status === 'queued').length;
+
+  return {
+    jobs,
+    queued: queuedCount,
+    running: runningCount,
+  };
+}
+
+/**
+ * Get full swarm status: unified list of all workflow runs with counts
+ * @param {number} [page=1] - Page number for pagination
+ * @returns {Promise<object>} - { runs, hasMore, counts }
+ */
+async function getSwarmStatus(page = 1) {
+  const data = await getWorkflowRuns(null, { page, perPage: 25 });
+
+  const runs = (data.workflow_runs || []).map(run => ({
+    run_id: run.id,
+    branch: run.head_branch,
+    status: run.status,
+    conclusion: run.conclusion,
+    workflow_name: run.name,
+    started_at: run.created_at,
+    updated_at: run.updated_at,
+    duration_seconds: Math.round((Date.now() - new Date(run.created_at).getTime()) / 1000),
+    html_url: run.html_url,
+  }));
+
+  return {
+    runs,
+    hasMore: page * 25 < (data.total_count || 0),
+  };
+}
+
+/**
+ * Trigger a workflow via workflow_dispatch
+ * @param {string} workflowId - Workflow file name (e.g., 'upgrade-event-handler.yml')
+ * @param {string} [ref='main'] - Git ref to run the workflow on
+ * @param {object} [inputs={}] - Workflow inputs
+ */
+async function triggerWorkflowDispatch(workflowId, ref = 'main', inputs = {}) {
+  const { GH_OWNER, GH_REPO } = process.env;
+  const res = await fetch(
+    `https://api.github.com/repos/${GH_OWNER}/${GH_REPO}/actions/workflows/${workflowId}/dispatches`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.GH_TOKEN}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ ref, inputs }),
+    }
+  );
+  if (!res.ok && res.status !== 204) {
+    const error = await res.text();
+    throw new Error(`GitHub API error: ${res.status} ${error}`);
+  }
+  return { success: true };
+}
+
+/**
+ * Fetch the session log (.jsonl) for a job from the GitHub repo at a specific commit.
+ * @param {string} jobId - The job ID (used to locate logs/{jobId}/)
+ * @param {string} commitSha - Git commit SHA to read from
+ * @returns {Promise<string>} - Log content or empty string if unavailable
+ */
+async function fetchJobLog(jobId, commitSha) {
+  if (!commitSha) return '';
+  const { GH_OWNER, GH_REPO } = process.env;
+  try {
+    const files = await githubApi(
+      `/repos/${GH_OWNER}/${GH_REPO}/contents/logs/${jobId}?ref=${encodeURIComponent(commitSha)}`
+    );
+    if (!Array.isArray(files)) return '';
+    const logFile = files.find(f => f.name.endsWith('.jsonl'));
+    if (!logFile || !logFile.download_url) return '';
+    const res = await fetch(logFile.download_url, {
+      headers: { 'Authorization': `Bearer ${process.env.GH_TOKEN}` },
+    });
+    if (!res.ok) return '';
+    return await res.text();
+  } catch (err) {
+    console.error('Failed to fetch job log:', err.message);
+    return '';
+  }
+}
+
+export {
+  githubApi,
+  getWorkflowRuns,
+  getWorkflowRunJobs,
+  getJobStatus,
+  getSwarmStatus,
+  triggerWorkflowDispatch,
+  fetchJobLog,
+};

package/lib/tools/openai.js

@@ -0,0 +1,35 @@
+/**
+ * Check if Whisper transcription is enabled
+ * @returns {boolean}
+ */
+function isWhisperEnabled() {
+  return Boolean(process.env.OPENAI_API_KEY);
+}
+
+/**
+ * Transcribe audio using OpenAI Whisper API
+ * @param {Buffer} audioBuffer - Audio file buffer
+ * @param {string} filename - Original filename (e.g., "voice.ogg")
+ * @returns {Promise<string>} Transcribed text
+ */
+async function transcribeAudio(audioBuffer, filename) {
+  const formData = new FormData();
+  formData.append('file', new Blob([audioBuffer]), filename);
+  formData.append('model', 'whisper-1');
+
+  const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${process.env.OPENAI_API_KEY}` },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`OpenAI API error: ${response.status} ${error}`);
+  }
+
+  const result = await response.json();
+  return result.text;
+}
+
+export { isWhisperEnabled, transcribeAudio };

package/lib/tools/telegram.js

@@ -0,0 +1,292 @@
+import { Bot } from 'grammy';
+import parseModePlugin from '@grammyjs/parse-mode';
+const { hydrateReply } = parseModePlugin;
+
+const MAX_LENGTH = 4096;
+
+/**
+ * Convert markdown to Telegram-compatible HTML.
+ * Handles: code blocks, inline code, links, bold, italic, strikethrough, headings, lists.
+ * Strips unsupported HTML tags.
+ * @param {string} text - Markdown text
+ * @returns {string} Telegram HTML
+ */
+function markdownToTelegramHtml(text) {
+  if (!text) return '';
+
+  const placeholders = [];
+  function placeholder(content) {
+    const id = `\x00PH${placeholders.length}\x00`;
+    placeholders.push(content);
+    return id;
+  }
+
+  // 1. Protect existing supported HTML tags (so they survive escaping)
+  text = text.replace(/<(\/?(b|i|s|u|code|pre|a)\b[^>]*)>/g, (match) => {
+    return placeholder(match);
+  });
+
+  // 2. Extract fenced code blocks (``` ... ```)
+  text = text.replace(/```[\w]*\n([\s\S]*?)```/g, (_, code) => {
+    return placeholder(`<pre>${escapeHtml(code.replace(/\n$/, ''))}</pre>`);
+  });
+
+  // 3. Extract inline code (` ... `)
+  text = text.replace(/`([^`\n]+)`/g, (_, code) => {
+    return placeholder(`<code>${escapeHtml(code)}</code>`);
+  });
+
+  // 4. Escape remaining HTML special chars (after code + existing tags are protected)
+  text = text.replace(/&/g, '&amp;');
+  text = text.replace(/</g, '&lt;');
+  text = text.replace(/>/g, '&gt;');
+
+  // 5. Links: [text](url)
+  text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  // 6. Bold: **text** or __text__
+  text = text.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+  text = text.replace(/__(.+?)__/g, '<b>$1</b>');
+
+  // 7. Italic: *text* or _text_ (but not inside words for underscores)
+  text = text.replace(/(?<!\w)\*([^*\n<]+)\*(?!\w)/g, '<i>$1</i>');
+  text = text.replace(/(?<!\w)_([^_\n<]+)_(?!\w)/g, '<i>$1</i>');
+
+  // 8. Strikethrough: ~~text~~
+  text = text.replace(/~~(.+?)~~/g, '<s>$1</s>');
+
+  // 9. Headings: ## text → bold (must be at line start)
+  text = text.replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>');
+
+  // 10. List items: - item or * item → bullet
+  text = text.replace(/^[\s]*[-*]\s+/gm, '• ');
+
+  // 11. Numbered list items: 1. item → keep as-is (already plain text friendly)
+
+  // 12. Restore placeholders
+  for (let i = 0; i < placeholders.length; i++) {
+    text = text.replace(`\x00PH${i}\x00`, placeholders[i]);
+  }
+
+  return text;
+}
+
+let bot = null;
+let currentToken = null;
+
+/**
+ * Get or create bot instance
+ * @param {string} token - Bot token from @BotFather
+ * @returns {Bot} grammY Bot instance
+ */
+function getBot(token) {
+  if (!bot || currentToken !== token) {
+    bot = new Bot(token);
+    bot.use(hydrateReply);
+    currentToken = token;
+  }
+  return bot;
+}
+
+/**
+ * Set webhook for a Telegram bot
+ * @param {string} botToken - Bot token from @BotFather
+ * @param {string} webhookUrl - HTTPS URL to receive updates
+ * @param {string} [secretToken] - Optional secret token for verification
+ * @returns {Promise<boolean>} - Success status
+ */
+async function setWebhook(botToken, webhookUrl, secretToken) {
+  const b = getBot(botToken);
+  const options = {};
+  if (secretToken) {
+    options.secret_token = secretToken;
+  }
+  return b.api.setWebhook(webhookUrl, options);
+}
+
+/**
+ * Smart split text into chunks that fit Telegram's limit
+ * Prefers splitting at paragraph > newline > sentence > space
+ * @param {string} text - Text to split
+ * @param {number} maxLength - Maximum chunk length
+ * @returns {string[]} Array of chunks
+ */
+function smartSplit(text, maxLength = MAX_LENGTH) {
+  if (text.length <= maxLength) return [text];
+
+  const chunks = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    const chunk = remaining.slice(0, maxLength);
+    let splitAt = -1;
+
+    // Try to split at natural boundaries (prefer earlier ones)
+    for (const delim of ['\n\n', '\n', '. ', ' ']) {
+      const idx = chunk.lastIndexOf(delim);
+      if (idx > maxLength * 0.3) {
+        splitAt = idx + delim.length;
+        break;
+      }
+    }
+
+    if (splitAt === -1) splitAt = maxLength;
+
+    chunks.push(remaining.slice(0, splitAt).trimEnd());
+    remaining = remaining.slice(splitAt).trimStart();
+  }
+
+  return chunks;
+}
+
+/**
+ * Escape HTML special characters
+ * @param {string} text - Text to escape
+ * @returns {string} Escaped text
+ */
+function escapeHtml(text) {
+  if (!text) return '';
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Send a message to a Telegram chat with HTML formatting
+ * Automatically splits long messages
+ * @param {string} botToken - Bot token from @BotFather
+ * @param {number|string} chatId - Chat ID to send message to
+ * @param {string} text - Message text (HTML formatted)
+ * @param {Object} [options] - Additional options
+ * @param {boolean} [options.disablePreview] - Disable link previews
+ * @returns {Promise<Object>} - Last message sent
+ */
+async function sendMessage(botToken, chatId, text, options = {}) {
+  const b = getBot(botToken);
+  text = markdownToTelegramHtml(text);
+  // Strip HTML comments — Telegram's HTML parser doesn't support them
+  text = text.replace(/<!--[\s\S]*?-->/g, '');
+  const chunks = smartSplit(text, MAX_LENGTH);
+
+  let lastMessage;
+  for (const chunk of chunks) {
+    lastMessage = await b.api.sendMessage(chatId, chunk, {
+      parse_mode: 'HTML',
+      link_preview_options: { is_disabled: options.disablePreview ?? false },
+    });
+  }
+
+  return lastMessage;
+}
+
+/**
+ * Format a job notification message
+ * @param {Object} params - Notification parameters
+ * @param {string} params.jobId - Full job ID
+ * @param {boolean} params.success - Whether job succeeded
+ * @param {string} params.summary - Job summary text
+ * @param {string} params.prUrl - PR URL
+ * @returns {string} Formatted HTML message
+ */
+function formatJobNotification({ jobId, success, summary, prUrl }) {
+  const emoji = success ? '\u2705' : '\u26a0\ufe0f';
+  const status = success ? 'complete' : 'had issues';
+  const shortId = jobId.slice(0, 8);
+
+  return `${emoji} <b>Job ${shortId}</b> ${status}
+
+${escapeHtml(summary)}
+
+<a href="${prUrl}">View PR</a>`;
+}
+
+/**
+ * Download a file from Telegram servers
+ * @param {string} botToken - Bot token from @BotFather
+ * @param {string} fileId - Telegram file_id
+ * @returns {Promise<{buffer: Buffer, filename: string}>}
+ */
+async function downloadFile(botToken, fileId) {
+  // Get file path from Telegram
+  const fileInfoRes = await fetch(
+    `https://api.telegram.org/bot${botToken}/getFile?file_id=${fileId}`
+  );
+  const fileInfo = await fileInfoRes.json();
+  if (!fileInfo.ok) {
+    throw new Error(`Telegram API error: ${fileInfo.description}`);
+  }
+
+  const filePath = fileInfo.result.file_path;
+
+  // Download file
+  const fileRes = await fetch(
+    `https://api.telegram.org/file/bot${botToken}/${filePath}`
+  );
+  const buffer = Buffer.from(await fileRes.arrayBuffer());
+  const filename = filePath.split('/').pop();
+
+  return { buffer, filename };
+}
+
+/**
+ * React to a message with an emoji
+ * @param {string} botToken - Bot token from @BotFather
+ * @param {number|string} chatId - Chat ID
+ * @param {number} messageId - Message ID to react to
+ * @param {string} [emoji='\ud83d\udc4d'] - Emoji to react with
+ */
+async function reactToMessage(botToken, chatId, messageId, emoji = '\ud83d\udc4d') {
+  const b = getBot(botToken);
+  await b.api.setMessageReaction(chatId, messageId, [{ type: 'emoji', emoji }]);
+}
+
+/**
+ * Start a repeating typing indicator for a chat.
+ * Returns a stop function. The indicator naturally expires after 5s,
+ * so we re-send with random gaps (5.5-8s) to look human.
+ * @param {string} botToken - Bot token from @BotFather
+ * @param {number|string} chatId - Chat ID
+ * @returns {Function} Call to stop the typing indicator
+ */
+function startTypingIndicator(botToken, chatId) {
+  const b = getBot(botToken);
+  let timeout;
+  let stopped = false;
+
+  function scheduleNext() {
+    if (stopped) return;
+    const delay = 5500 + Math.random() * 2500;
+    timeout = setTimeout(() => {
+      if (stopped) return;
+      b.api.sendChatAction(chatId, 'typing').catch(() => {});
+      scheduleNext();
+    }, delay);
+  }
+
+  b.api.sendChatAction(chatId, 'typing').catch(() => {});
+  scheduleNext();
+
+  return () => {
+    stopped = true;
+    clearTimeout(timeout);
+  };
+}
+
+export {
+  getBot,
+  setWebhook,
+  sendMessage,
+  smartSplit,
+  escapeHtml,
+  markdownToTelegramHtml,
+  formatJobNotification,
+  downloadFile,
+  reactToMessage,
+  startTypingIndicator,
+};

package/lib/triggers.js

@@ -0,0 +1,118 @@
+import fs from 'fs';
+import { triggersFile, triggersDir } from './paths.js';
+import { executeAction } from './actions.js';
+
+/**
+ * Shell-escape a string to prevent command injection when used in shell commands.
+ * Wraps in single quotes and escapes any embedded single quotes.
+ */
+function shellEscape(str) {
+  return "'" + String(str).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Replace {{body.field}} templates with values from request context.
+ * @param {string} template - String with {{body.field}} placeholders
+ * @param {Object} context - { body, query, headers }
+ * @param {Object} [opts] - { escape: 'shell' } to shell-escape substituted values
+ * @returns {string}
+ */
+function resolveTemplate(template, context, opts = {}) {
+  const escape = opts.escape === 'shell' ? shellEscape : (v) => v;
+  return template.replace(/\{\{(\w+)(?:\.(\w+))?\}\}/g, (match, source, field) => {
+    const data = context[source];
+    if (data === undefined) return match;
+    if (!field) {
+      const raw = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+      return escape(raw);
+    }
+    if (data[field] !== undefined) return escape(String(data[field]));
+    return match;
+  });
+}
+
+/**
+ * Execute all actions for a trigger (fire-and-forget)
+ * @param {Object} trigger - Trigger config object
+ * @param {Object} context - { body, query, headers }
+ */
+async function executeActions(trigger, context) {
+  for (const action of trigger.actions) {
+    try {
+      const resolved = { ...action };
+      // Shell-escape template values in commands to prevent injection from HTTP input
+      if (resolved.command) resolved.command = resolveTemplate(resolved.command, context, { escape: 'shell' });
+      if (resolved.job) resolved.job = resolveTemplate(resolved.job, context);
+      const result = await executeAction(resolved, { cwd: triggersDir, data: context.body });
+      console.log(`[TRIGGER] ${trigger.name}: ${result || 'ran'}`);
+    } catch (err) {
+      console.error(`[TRIGGER] ${trigger.name}: error - ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Load triggers from TRIGGERS.json and return trigger map + fire function
+ * @returns {{ triggerMap: Map, fireTriggers: Function }}
+ */
+function loadTriggers() {
+  const triggerFile = triggersFile;
+  const triggerMap = new Map();
+
+  console.log('\n--- Triggers ---');
+
+  if (!fs.existsSync(triggerFile)) {
+    console.log('No TRIGGERS.json found');
+    console.log('----------------\n');
+    return { triggerMap, fireTriggers: () => {} };
+  }
+
+  const triggers = JSON.parse(fs.readFileSync(triggerFile, 'utf8'));
+
+  for (const trigger of triggers) {
+    if (trigger.enabled === false) continue;
+
+    if (!triggerMap.has(trigger.watch_path)) {
+      triggerMap.set(trigger.watch_path, []);
+    }
+    triggerMap.get(trigger.watch_path).push(trigger);
+  }
+
+  const activeCount = [...triggerMap.values()].reduce((sum, arr) => sum + arr.length, 0);
+
+  if (activeCount === 0) {
+    console.log('No active triggers');
+  } else {
+    for (const [watchPath, pathTriggers] of triggerMap) {
+      for (const t of pathTriggers) {
+        const actionTypes = t.actions.map(a => a.type || 'agent').join(', ');
+        console.log(`  ${t.name}: ${watchPath} (${actionTypes})`);
+      }
+    }
+  }
+
+  console.log('----------------\n');
+
+  /**
+   * Fire matching triggers for a given path (non-blocking)
+   * @param {string} path - Request path (e.g., '/webhook')
+   * @param {Object} body - Request body
+   * @param {Object} [query={}] - Query parameters
+   * @param {Object} [headers={}] - Request headers
+   */
+  function fireTriggers(path, body, query = {}, headers = {}) {
+    const matched = triggerMap.get(path);
+    if (matched) {
+      const context = { body, query, headers };
+      for (const trigger of matched) {
+        executeActions(trigger, context).catch(err => {
+          console.error(`[TRIGGER] ${trigger.name}: unhandled error - ${err.message}`);
+        });
+      }
+    }
+  }
+
+  return { triggerMap, fireTriggers };
+}
+
+export { loadTriggers };