Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

8.4 KB
Raw Blame
import type { BotStore } from './store.js';
import type { BotQueue } from './queue.js';
import { cronMinGapMinutes } from './tools/bot-schedule.js';
import { validateBotManifest } from './store.js';
import type { BotRunRecord } from './types.js';
import type { BotJournal } from './journal.js';

export interface DoctorFinding {
  botId: string;
  severity: 'error' | 'warning';
  check: string;
  detail: string;
}

export interface DoctorReport {
  findings: DoctorFinding[];
  healthy: boolean;
  checked: number;
}

export interface DoctorDeps {
  store: BotStore;
  queue: BotQueue;
  journalFor: (botId: string) => BotJournal;
  /** Scheduled manifests by id (bot:<id>:<name>) for next-run overdue checks. */
  scheduledRoutineIds?: string[];
  /** Grace window (minutes) before an overdue schedule counts as not firing. */
  graceMinutes?: number;
}

/**
 * Read-only fleet health check — the Hermes `cron doctor` pattern:
 * groups per-bot issues no other surface shows at once. Exit-code bearing:
 * `healthy === false` maps to exit 1 so watchdogs/CI can gate on it.
 */
export function runBotDoctor(deps: DoctorDeps): DoctorReport {
  const findings: DoctorFinding[] = [];
  const manifests = deps.store.list();
  const dlqByBot = new Map<string, number>();
  for (const entry of deps.queue.listDlq()) {
    dlqByBot.set(entry.botId, (dlqByBot.get(entry.botId) ?? 0) + 1);
  }

  for (const manifest of manifests) {
    const errors = validateBotManifest(manifest);
    if (errors.length > 0) {
      findings.push({ botId: manifest.id, severity: 'error', check: 'config', detail: errors.join('; ') });
    }

    // Malformed permissions.yaml entries (missing/empty `scope` — typically a
    // hand-edit typo) are skipped by the registry at build time; flag them so
    // the grant silently NOT applying is visible (the cron-doctor class of
    // "configured but not effective").
    const perms = deps.store.readPermissions(manifest.id);
    const malformed = (perms.paths ?? []).filter(p => !p || typeof p.scope !== 'string' || p.scope.trim().length === 0);
    if (malformed.length > 0) {
      findings.push({
        botId: manifest.id,
        severity: 'error',
        check: 'permissions',
        detail: `${malformed.length} path-scope entr(ies) missing a "scope" value in permissions.yaml — the grant is skipped (check for typos like "socpe:")`,
      });
    }

    // Fleet hierarchy integrity: a crew bot whose lead no longer exists is
    // orphaned — it can never be dispatched to, monitored, or retired.
    if (manifest.parent && !manifests.some(m => m.id === manifest.parent)) {
      findings.push({
        botId: manifest.id,
        severity: 'error',
        check: 'fleet',
        detail: `Crew bot's lead "${manifest.parent}" no longer exists — detach with /bots edit or re-point the parent`,
      });
    }

    // ADR-020: a bot whose unattended runs mostly produce nothing is
    // spending tokens on commentary — the owner should look at its persona.
    const recent = deps.journalFor(manifest.id).read(manifest.id, 20).filter(r => r.outcome !== undefined && (r.trigger === 'cron' || r.trigger === 'api'));
    if (recent.length >= 4) {
      const none = recent.filter(r => r.outcome === 'none').length;
      if (none * 2 >= recent.length) {
        findings.push({
          botId: manifest.id,
          severity: 'warning',
          check: 'outcome',
          detail: `${none} of the last ${recent.length} unattended runs produced no deliverable or action — check the persona for instructions that reward activity over results`,
        });
      }
      const claimed = recent.filter(r => r.claimedWithoutAction).length;
      if (claimed > 0) {
        findings.push({ botId: manifest.id, severity: 'warning', check: 'outcome', detail: `${claimed} run(s) claimed delivery or execution the tool trace does not show` });
      }
    }
    const routineState = deps.store.readRoutineState(manifest.id);
    for (const [key, info] of Object.entries(routineState.paused)) {
      findings.push({ botId: manifest.id, severity: 'warning', check: 'routine', detail: `routine "${key.split(':').pop()}" paused since ${info.since.slice(0, 16).replace('T', ' ')}: ${info.reason} — /bots start ${manifest.id} resumes it` });
    }
    const homeGrant = (perms.paths ?? []).find(p => p && typeof p.scope === 'string' && /^~[\\/]?$/.test(p.scope.trim()) && p.write);
    if (homeGrant) {
      findings.push({ botId: manifest.id, severity: 'warning', check: 'permissions', detail: 'write access to the whole home directory — an unattended bot can write anywhere; prefer specific scopes (/bots permissions)' });
    }
    const dlqDepth = dlqByBot.get(manifest.id) ?? 0;
    if (dlqDepth > 0) {
      findings.push({
        botId: manifest.id,
        severity: dlqDepth > 5 ? 'error' : 'warning',
        check: 'dlq',
        detail: `${dlqDepth} dead-lettered job(s) awaiting review or replay`,
      });
    }

    const journal = deps.journalFor(manifest.id);
    const counts = journal.counts(manifest.id);
    if (counts.total > 0) {
      const recent = journal.read(manifest.id, 5);
      const last = recent[recent.length - 1];
      if (last && last.state === 'failed') {
        findings.push({
          botId: manifest.id,
          severity: 'error',
          check: 'last-run',
          detail: `Last run ${last.runId} failed${last.reasonCode ? ` [reason: ${last.reasonCode}]` : ''}${last.error ? `: ${last.error.slice(0, 120)}` : ''}`,
        });
      }
    }
    if (manifest.enabled === false) continue;
    // Liveness: an enabled bot with a declared cadence that has not run in
    // twice its interval (plus grace) is stale — something upstream (the
    // scheduler, a held queue, a provider) is keeping it from its routine.
    const cadences = (manifest.schedules ?? []).map(r => cronMinGapMinutes(r.cron)).filter(n => Number.isFinite(n));
    if (cadences.length > 0) {
      const expectedMin = Math.min(...cadences);
      const grace = deps.graceMinutes ?? 60;
      const last = deps.journalFor(manifest.id).read(manifest.id, 1)[0];
      const lastAt = last ? (last.turnStartedAt ?? last.startedAt) : (manifest.createdAt ? Date.parse(manifest.createdAt) : 0);
      const staleAfterMs = (2 * expectedMin + grace) * 60_000;
      if (lastAt > 0 && Date.now() - lastAt > staleAfterMs) {
        const paused = Object.keys(deps.store.readRoutineState(manifest.id).paused).length > 0;
        findings.push({
          botId: manifest.id,
          severity: 'warning',
          check: 'stale',
          detail: `last run ${Math.round((Date.now() - lastAt) / 3_600_000)}h ago but a routine is declared every ${expectedMin} min${paused ? ' (a routine is cooling down)' : ' — check the scheduler and /bots start'}`,
        });
      }
    }
    for (const routine of manifest.schedules ?? []) {
      const id = `bot:${manifest.id}:${routine.name}`;
      if (deps.scheduledRoutineIds && !deps.scheduledRoutineIds.includes(id)) {
        findings.push({
          botId: manifest.id,
          severity: 'warning',
          check: 'schedule-registered',
          detail: `Routine "${routine.name}" is configured in bot.yaml but not registered in the scheduler — run \`mercury restart\` to register bot routines`,
        });
      }
    }
  }

  // Bots referenced in schedules or DLQ but missing from the profile store.
  for (const [botId, depth] of dlqByBot) {
    if (!manifests.some(m => m.id === botId)) {
      findings.push({ botId, severity: 'warning', check: 'orphan-dlq', detail: `${depth} DLQ entries for a bot with no profile` });
    }
  }

  return {
    findings,
    healthy: findings.every(f => f.severity !== 'error'),
    checked: manifests.length,
  };
}

export function formatDoctorReport(report: DoctorReport): string {
  if (report.findings.length === 0) {
    return `✅ Bot fleet healthy — ${report.checked} bot(s) checked, nothing actionable.`;
  }
  const lines: string[] = [];
  const errors = report.findings.filter(f => f.severity === 'error');
  const warnings = report.findings.filter(f => f.severity === 'warning');
  lines.push(`⚠ Bot fleet: ${errors.length} actionable, ${report.findings.length - errors.length} warning(s) — ${report.checked} bot(s) checked`, '');
  for (const finding of report.findings) {
    const icon = finding.severity === 'error' ? '❌' : '⚠️';
    lines.push(`${icon} [${finding.botId}] ${finding.check}: ${finding.detail}`);
  }
  return lines.join('\n');
}

// Re-exported for the doctor UI's last-run window check.
export type { BotRunRecord };