@adityaaria/agent-os 1.0.0

package/scripts/lib/telegram-bot-utils.mjs

@@ -0,0 +1,413 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectRun, collectRuns } from './run-utils.mjs';
+import { escapeTelegramMarkdown } from './telegram-utils.mjs';
+import { appendAuditEntry, readAuditLog } from './telegram-audit-log.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
+
+export function readTelegramUpdatesFromFile(filePath, baseDir = process.cwd()) {
+  const raw = JSON.parse(fs.readFileSync(path.resolve(baseDir, filePath), 'utf8'));
+  return normalizeTelegramUpdates(raw);
+}
+
+export function normalizeTelegramUpdates(raw) {
+  if (Array.isArray(raw)) return raw;
+  if (Array.isArray(raw?.result)) return raw.result;
+  return [];
+}
+
+export function createAllowedChats(allowedChatId) {
+  return new Set(String(allowedChatId ?? '').split(',').map((id) => id.trim()).filter(Boolean));
+}
+
+export function createTelegramAccessControl({ allowedChatId, roles }) {
+  const allowedChats = createAllowedChats(allowedChatId);
+  const roleMap = buildRoleMap(roles);
+  return { allowedChats, roleMap, hasConfiguredRoles: roleMap.size > 0 };
+}
+
+export function processTelegramUpdates({ updates, allowedChats, accessControl, runRoot, channelConfig, auditRunRoot }) {
+  const control = accessControl ?? { allowedChats, roleMap: new Map(), hasConfiguredRoles: false };
+  return updates.map((update) => processTelegramUpdate({ update, accessControl: control, runRoot, channelConfig, auditRunRoot })).filter(Boolean);
+}
+
+export function writeTelegramBotOutput({ channelContext, channelName, responses, outputOverride, mode = 'dry-run' }) {
+  const outputPath = path.resolve(
+    channelContext.outputBaseDir,
+    outputOverride ?? channelContext.channel.botOutput ?? 'reports/telegram-bot-responses.json'
+  );
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify({
+    channel: channelName,
+    mode,
+    responses
+  }, null, 2)}\n`);
+  return outputPath;
+}
+
+function buildRoleMap(roles) {
+  const roleMap = new Map();
+  for (const [role, chatIds] of Object.entries(roles ?? {})) {
+    for (const chatId of Array.isArray(chatIds) ? chatIds : [chatIds]) {
+      if (chatId !== null && chatId !== undefined) roleMap.set(String(chatId), role);
+    }
+  }
+  return roleMap;
+}
+
+function processTelegramUpdate({ update, accessControl, runRoot, channelConfig, auditRunRoot }) {
+  const incoming = extractIncomingCommand(update);
+  if (!incoming) return null;
+
+  const chatId = incoming.chatId;
+  const parsed = parseCommand(incoming.text);
+  const logEntry = {
+    chatId,
+    command: parsed.command,
+    argument: parsed.argument,
+    action: 'command_received'
+  };
+
+  if (!accessControl.allowedChats.has(chatId)) {
+    logEntry.action = 'access_denied';
+    logEntry.result = 'denied';
+    appendAuditEntry({ runRoot: auditRunRoot, entry: logEntry });
+    return {
+      chatId,
+      allowed: false,
+      command: parsed.command,
+      text: 'This chat is not authorized to control Agent OS.'
+    };
+  }
+
+  const role = resolveRole(accessControl, chatId);
+  logEntry.role = role;
+
+  const denied = denyForRole({ parsed, role });
+  if (denied) {
+    logEntry.action = 'role_denied';
+    logEntry.result = 'denied';
+    appendAuditEntry({ runRoot: auditRunRoot, entry: logEntry });
+    return {
+      chatId,
+      allowed: true,
+      role,
+      command: parsed.command,
+      text: denied
+    };
+  }
+
+  const isCallback = !!incoming.callbackQueryId;
+  if (parsed.command === 'run' && isCallback && isApprovalExpired(parsed.expiresAt)) {
+    logEntry.action = 'approval_expired';
+    logEntry.result = 'expired';
+    logEntry.runId = parsed.argument;
+    appendAuditEntry({ runRoot: auditRunRoot, entry: logEntry });
+    return {
+      chatId,
+      allowed: true,
+      role,
+      command: parsed.command,
+      callbackQueryId: incoming.callbackQueryId,
+      text: '⏰ Approval expired. This approval button is no longer valid.'
+    };
+  }
+
+  const response = dispatchCommand({ parsed, runRoot, channelConfig });
+  if (parsed.command === 'run') {
+    logEntry.action = 'run_executed';
+    logEntry.runId = response.runId || parsed.argument;
+    logEntry.result = response.text.startsWith('Executed run') ? 'success' : 'error';
+  } else if (['bug', 'enhancement', 'audit', 'test', 'analyze_project', 'audit_framework'].includes(parsed.command)) {
+    logEntry.action = 'run_created';
+    logEntry.runId = response.runId;
+    logEntry.result = response.text.startsWith('Created run') ? 'success' : 'error';
+  } else {
+    logEntry.action = 'command_received';
+    logEntry.result = 'success';
+  }
+  
+  appendAuditEntry({ runRoot: auditRunRoot, entry: logEntry });
+
+  return {
+    chatId,
+    allowed: true,
+    role,
+    command: parsed.command,
+    callbackQueryId: incoming.callbackQueryId,
+    ...response
+  };
+}
+
+export function isApprovalExpired(expiresAt, nowFn = () => Math.floor(Date.now() / 1000)) {
+  if (expiresAt === null) return true;
+  return nowFn() > expiresAt;
+}
+
+function extractIncomingCommand(update) {
+  const message = update.message ?? update.edited_message;
+  if (message?.chat?.id && typeof message.text === 'string') {
+    return {
+      chatId: String(message.chat.id),
+      text: message.text
+    };
+  }
+
+  const callback = update.callback_query;
+  if (callback?.message?.chat?.id && typeof callback.data === 'string') {
+    return {
+      chatId: String(callback.message.chat.id),
+      text: callback.data,
+      callbackQueryId: callback.id
+    };
+  }
+
+  return null;
+}
+
+function resolveRole(accessControl, chatId) {
+  if (!accessControl.hasConfiguredRoles) return 'admin';
+  return accessControl.roleMap.get(chatId) ?? 'viewer';
+}
+
+function denyForRole({ parsed, role }) {
+  if (role === 'admin') return null;
+  const readCommands = new Set(['help', 'start', 'skills', 'runs', 'status']);
+  const planCommands = new Set(['bug', 'enhancement', 'audit', 'test', 'analyze_project', 'audit_framework']);
+
+  if (readCommands.has(parsed.command)) return null;
+  if (parsed.command === 'history' && ['admin', 'approver'].includes(role)) return null;
+  if (planCommands.has(parsed.command) && ['operator', 'approver'].includes(role)) return null;
+  if (parsed.command === 'run' && role === 'approver') return null;
+
+  return `Role ${escapeTelegramMarkdown(role)} is not permitted to use /${escapeTelegramMarkdown(parsed.command)}.`;
+}
+
+function parseCommand(text) {
+  const [rawCommand, ...rest] = text.trim().split(/\s+/);
+  const command = rawCommand.replace(/^\//, '').split('@')[0].toLowerCase();
+  
+  let argument = rest.join(' ').trim();
+  let expiresAt = null;
+
+  if (command === 'run') {
+    const timeMatch = argument.match(/\bt=(\d+)$/);
+    if (timeMatch) {
+      expiresAt = parseInt(timeMatch[1], 10);
+      argument = argument.replace(/\bt=\d+$/, '').trim();
+    }
+  }
+
+  return {
+    command,
+    argument,
+    expiresAt
+  };
+}
+
+function dispatchCommand({ parsed, runRoot, channelConfig }) {
+  if (parsed.command === 'help' || parsed.command === 'start') return { text: helpText() };
+  if (parsed.command === 'skills') return { text: skillsText() };
+  if (parsed.command === 'runs') return { text: runsText(runRoot) };
+  if (parsed.command === 'history') return { text: historyText(runRoot, parsed.argument) };
+  if (parsed.command === 'status') return { text: statusText(runRoot, parsed.argument) };
+  if (parsed.command === 'run') return executeRun(runRoot, parsed.argument);
+
+  const prompt = promptFromCommand(parsed);
+  if (prompt !== null) return createRunFromPrompt({ command: parsed.command, prompt, runRoot, channelConfig });
+
+  return { text: `Unsupported command: /${escapeTelegramMarkdown(parsed.command)}. Use /help or /skills.` };
+}
+
+function helpText() {
+  return [
+    '*Agent OS Bot Commands*',
+    '/skills - list supported skill commands',
+    '/runs - list known runs',
+    '/history [limit] - view audit log history (admin/approver only)',
+    '/status <run-id> - summarize a run',
+    '/run <run-id> - execute a reviewed run',
+    '/bug <text> - create a bug-fix run plan',
+    '/enhancement <text> - create an enhancement run plan',
+    '/audit <text> - create an audit run plan',
+    '/test <text> - create a test run plan',
+    '/analyze_project <text> - create a project-onboarding run plan',
+    '/audit_framework - create a framework self-audit run plan'
+  ].join('\n');
+}
+
+function skillsText() {
+  return [
+    '*Available Agent OS skills*',
+    '/bug - bug-fix',
+    '/enhancement - enhancement',
+    '/audit - audit',
+    '/test - selenium-e2e',
+    '/analyze_project - project-onboarding',
+    '/audit_framework - self-audit',
+    '/status - run status',
+    '/history - view audit log',
+    '/run - reviewed run execution',
+    '/runs - run list'
+  ].join('\n');
+}
+
+function runsText(runRoot) {
+  try {
+    const runs = collectRuns(runRoot);
+    if (runs.length === 0) return 'No runs found.';
+    return runs.map((run) => `${escapeTelegramMarkdown(run.runId)}: ${escapeTelegramMarkdown(run.status)}`).join('\n');
+  } catch (err) {
+    return `No runs found. ${escapeTelegramMarkdown(err.message)}`;
+  }
+}
+
+function statusText(runRoot, runId) {
+  if (!runId) return 'Usage: /status <run-id>';
+  try {
+    const run = collectRun(path.join(runRoot, runId));
+    return [
+      `Run ID: ${escapeTelegramMarkdown(run.runId)}`,
+      `Status: ${escapeTelegramMarkdown(run.status)}`,
+      `Steps: ${run.counts.passed}/${run.total} passed, ${run.counts.failed} failed, ${run.counts.blocked} blocked`
+    ].join('\n');
+  } catch (err) {
+    return `Run not found: ${escapeTelegramMarkdown(runId)}. ${escapeTelegramMarkdown(err.message)}`;
+  }
+}
+
+function promptFromCommand(parsed) {
+  const argument = parsed.argument;
+  const map = {
+    bug: `BUG: ${argument}`,
+    enhancement: `ENHANCEMENT: ${argument}`,
+    audit: `AUDIT: ${argument}`,
+    test: `TEST: ${argument}`,
+    analyze_project: `ANALYZE PROJECT: ${argument || 'Initialize this repository'}`,
+    audit_framework: 'AUDIT FRAMEWORK'
+  };
+  if (!Object.hasOwn(map, parsed.command)) return null;
+  if (!argument && parsed.command !== 'audit_framework' && parsed.command !== 'analyze_project') {
+    return '';
+  }
+  return map[parsed.command];
+}
+
+function historyText(runRoot, argument) {
+  const logs = readAuditLog({ runRoot });
+  if (logs.length === 0) {
+    return 'No audit history available.';
+  }
+
+  let limit = 5;
+  if (argument) {
+    const parsedLimit = parseInt(argument.trim(), 10);
+    if (!isNaN(parsedLimit) && parsedLimit > 0) {
+      limit = Math.min(parsedLimit, 20); // Cap at 20 to avoid exceeding Telegram message size limits
+    }
+  }
+
+  const entries = logs.slice(-limit).reverse(); // Get latest N entries and show newest first
+  const lines = [`*Telegram Audit Log (Last ${entries.length} entries)*\n`];
+
+  for (const entry of entries) {
+    const time = new Date(entry.timestamp).toISOString().replace('T', ' ').substring(0, 19);
+    const statusIcon = entry.status === 'success' ? '✅' : '❌';
+    lines.push(`🕒 \`${time}\` | ${statusIcon}`);
+    lines.push(`👤 *User*: \`${escapeTelegramMarkdown(entry.user || 'Unknown')}\``);
+    lines.push(`🛠 *Action*: ${escapeTelegramMarkdown(entry.action || 'Unknown')}`);
+    if (entry.status === 'denied') {
+      lines.push(`🛑 *Reason*: ${escapeTelegramMarkdown(entry.reason || 'Denied')}`);
+    }
+    lines.push(' ');
+  }
+
+  return lines.join('\n');
+}
+
+function createRunFromPrompt({ command, prompt, runRoot, channelConfig }) {
+  if (!prompt) {
+    return { text: `Usage: /${escapeTelegramMarkdown(command)} <description>` };
+  }
+
+  const runId = `tg-${command}-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  const result = spawnSync(process.execPath, [
+    path.join(repoRoot, 'scripts', 'orchestrate.mjs'),
+    '--run-root',
+    runRoot,
+    '--run-id',
+    runId,
+    prompt
+  ], {
+    cwd: repoRoot,
+    encoding: 'utf8'
+  });
+
+  if (result.status !== 0) {
+    return { text: `Failed to create run: ${escapeTelegramMarkdown(result.stderr || result.stdout)}` };
+  }
+
+  const plan = JSON.parse(result.stdout);
+  const ttlMinutes = channelConfig?.approvalTtlMinutes ?? 15;
+  return {
+    runId,
+    replyMarkup: approvalReplyMarkup(runId, { ttlMinutes }),
+    text: [
+      `Created run: ${escapeTelegramMarkdown(runId)}`,
+      `Trigger: ${escapeTelegramMarkdown(plan.trigger)}`,
+      `Skill chain: ${escapeTelegramMarkdown(plan.skillChain.join(' -> '))}`,
+      'Execution is not automatic. Review the plan before running execution.'
+    ].join('\n')
+  };
+}
+
+function approvalReplyMarkup(runId, { ttlMinutes = 15 } = {}) {
+  const expiresAt = Math.floor(Date.now() / 1000) + ttlMinutes * 60;
+  return {
+    inline_keyboard: [
+      [
+        {
+          text: 'Approve run',
+          callback_data: `/run ${runId} t=${expiresAt}`
+        }
+      ],
+      [
+        {
+          text: 'View status',
+          callback_data: `/status ${runId}`
+        }
+      ]
+    ]
+  };
+}
+
+function executeRun(runRoot, runId) {
+  if (!runId) return { text: 'Usage: /run <run-id>' };
+
+  const result = spawnSync(process.execPath, [
+    path.join(repoRoot, 'scripts', 'run-execution.mjs'),
+    '--run-dir',
+    path.join(runRoot, runId)
+  ], {
+    cwd: repoRoot,
+    encoding: 'utf8'
+  });
+
+  if (result.status !== 0) {
+    return { text: `Failed to execute run: ${escapeTelegramMarkdown(result.stderr || result.stdout)}` };
+  }
+
+  const execution = JSON.parse(result.stdout);
+  return {
+    runId,
+    text: [
+      `Executed run: ${escapeTelegramMarkdown(runId)}`,
+      `Status: ${escapeTelegramMarkdown(execution.status)}`,
+      `Steps: ${execution.steps}`
+    ].join('\n')
+  };
+}

package/scripts/lib/telegram-utils.mjs

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function escapeTelegramMarkdown(value) {
+  return String(value ?? '').replace(/([_*[\]()`])/g, '\\$1');
+}
+
+function statusCounts(run) {
+  return `${run.counts.passed}/${run.total} passed, ${run.counts.failed} failed, ${run.counts.blocked} blocked`;
+}
+
+export function renderTelegramRunReport(runs) {
+  const rows = Array.isArray(runs) ? runs : [runs];
+  const lines = ['*Agent OS Run Report*'];
+  for (const run of rows) {
+    lines.push(`\nRun ID: ${escapeTelegramMarkdown(run.runId)}`);
+    lines.push(`Status: *${escapeTelegramMarkdown(run.status.toUpperCase())}* (${statusCounts(run)})`);
+    if (run.plan) {
+      lines.push(`Trigger: ${escapeTelegramMarkdown(run.plan.trigger)}`);
+      lines.push(`Prompt: ${escapeTelegramMarkdown(run.plan.prompt)}`);
+    }
+    if (run.steps && run.steps.length > 0) {
+      lines.push('\n*Execution Steps:*');
+      run.steps.forEach((step) => {
+        lines.push(`- Step ${step.step}: ${escapeTelegramMarkdown(step.skill)} (${escapeTelegramMarkdown(step.status)})`);
+      });
+    }
+    if (run.reportDetails?.evidence && run.reportDetails.evidence !== 'N/A. Reason: Skills were not executed by this stub.') {
+      lines.push('\n*Test Evidence:*');
+      lines.push(escapeTelegramMarkdown(run.reportDetails.evidence));
+    }
+  }
+  return lines.join('\n');
+}
+
+export function renderTelegramLifecycleAlert(runs, event) {
+  const rows = Array.isArray(runs) ? runs : [runs];
+  const run = rows[0];
+  const eventLabel = escapeTelegramMarkdown(String(event ?? run.status).toUpperCase());
+  const lines = ['*Agent OS Lifecycle Alert*'];
+  lines.push(`Event: *${eventLabel}*`);
+  lines.push(`Run ID: ${escapeTelegramMarkdown(run.runId)}`);
+  lines.push(`Status: *${escapeTelegramMarkdown(run.status.toUpperCase())}* (${statusCounts(run)})`);
+  if (run.plan) {
+    lines.push(`Trigger: ${escapeTelegramMarkdown(run.plan.trigger)}`);
+    lines.push(`Prompt: ${escapeTelegramMarkdown(run.plan.prompt)}`);
+  }
+
+  const relevantSteps = (run.steps ?? []).filter((step) => ['failed', 'blocked'].includes(step.status));
+  if (relevantSteps.length > 0) {
+    lines.push('\n*Attention Required:*');
+    relevantSteps.forEach((step) => {
+      lines.push(`- Step ${step.step}: ${escapeTelegramMarkdown(step.skill)} (${escapeTelegramMarkdown(step.status)})`);
+    });
+  }
+
+  return lines.join('\n');
+}
+
+export function renderTelegramTestMessage(channelName) {
+  return [
+    '*Agent OS Telegram Test*',
+    `Channel: ${escapeTelegramMarkdown(channelName)}`,
+    'Status: configuration reachable'
+  ].join('\n');
+}
+
+export function createTelegramMessage({ runs, event, test = false, channelName = 'telegram' }) {
+  if (test) {
+    return {
+      parse_mode: 'Markdown',
+      text: renderTelegramTestMessage(channelName)
+    };
+  }
+
+  return {
+    parse_mode: 'Markdown',
+    text: event ? renderTelegramLifecycleAlert(runs, event) : renderTelegramRunReport(runs)
+  };
+}
+
+export function telegramEnv(channel) {
+  const botTokenEnv = channel.botTokenEnv ?? 'AGENT_OS_TELEGRAM_BOT_TOKEN';
+  const chatIdEnv = channel.chatIdEnv ?? 'AGENT_OS_TELEGRAM_CHAT_ID';
+  return {
+    botTokenEnv,
+    chatIdEnv,
+    botToken: process.env[botTokenEnv] ?? null,
+    chatId: process.env[chatIdEnv] ?? null
+  };
+}
+
+export function buildTelegramRequest({ channel, message, botToken, chatId }) {
+  const apiBaseUrl = channel.apiBaseUrl ?? 'https://api.telegram.org';
+  return {
+    method: 'POST',
+    url: `${apiBaseUrl}/bot${botToken}/sendMessage`,
+    body: {
+      chat_id: chatId,
+      ...message
+    }
+  };
+}
+
+export async function sendTelegramRequest({ channel, channelContext, message, botToken, chatId }) {
+  const telegramRequest = buildTelegramRequest({ channel, message, botToken, chatId });
+
+  if (channel.mockRequestFile) {
+    const mockRequestPath = path.resolve(channelContext.outputBaseDir, channel.mockRequestFile);
+    fs.mkdirSync(path.dirname(mockRequestPath), { recursive: true });
+    fs.writeFileSync(mockRequestPath, `${JSON.stringify(telegramRequest, null, 2)}\n`);
+    return { mocked: true };
+  }
+
+  const response = await fetch(telegramRequest.url, {
+    method: telegramRequest.method,
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(telegramRequest.body)
+  });
+
+  if (!response.ok) {
+    const responseText = await response.text();
+    throw new Error(`Telegram send failed (${response.status}): ${responseText}`);
+  }
+
+  return { mocked: false };
+}