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.

9.2 KB
Raw Blame
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { getMercuryHome } from '../utils/config.js';
import { logger } from '../utils/logger.js';
import type { BotStore } from './store.js';
import type { BotManifest, BotPermissionsFile } from './types.js';

/**
 * Bot bundles — plug-and-play import/export (ADR-012 extension).
 *
 * A bundle is ONE transport-agnostic JSON document describing a bot or a
 * whole fleet: manifests, personas, and permissions. It is what makes the
 * on-disk fleet layout shareable and recreatable anywhere Mercury runs —
 * the CLI today, the local web dashboard, Mercury Code, or a third-party
 * site using Mercury as its agent backend (the same document can arrive via
 * file upload, HTTP POST, or paste).
 *
 * What is INCLUDED (the bot's identity + behavior):
 *   bot.yaml (sanitized), persona.md, permissions.yaml, skills/*.md
 * What is NEVER included (local state and secrets — they do not travel):
 *   sandbox/, journal.jsonl*, .env
 *
 * Fleet shape mirrors the physical layout: the lead is the bundle root; crew
 * entries keep their `parent` fields, which import resolves against ids
 * INSIDE the bundle (a crew exported alone exports as a solo — its lead did
 * not travel with it).
 */

export const BOT_BUNDLE_FORMAT = 'mercury-bot-bundle';
export const BOT_BUNDLE_VERSION = 1;

export interface BotBundleEntry {
  id: string;
  name: string;
  description?: string;
  /** Sanitized bot.yaml content (volatile fields stripped). */
  manifest: Record<string, unknown>;
  persona: string;
  /** The single source of truth for permissions, as-is. */
  permissions: BotPermissionsFile;
  /** Skill files (name → text content) when export included skills. */
  skills?: Record<string, string>;
}

export interface BotBundle {
  format: typeof BOT_BUNDLE_FORMAT;
  version: number;
  kind: 'bot' | 'fleet';
  /** The bundle's entry-point bot id. */
  root: string;
  exportedAt: string;
  /** Lead-first, parents-before-children order. */
  bots: BotBundleEntry[];
}

export interface BundleImportReport {
  created: string[];
  skipped: Array<{ id: string; reason: string }>;
}

/** Manifest fields that describe THIS machine's runtime, not the bot. */
const VOLATILE_MANIFEST_FIELDS = ['createdAt', 'updatedAt'];

/**
 * Build a shareable bundle from a bot — or, for a fleet lead, the lead plus
 * its whole crew tree (recursively, matching the nested directory layout).
 */
export function buildBotBundle(store: BotStore, rootId: string, opts: { withSkills?: boolean } = {}): BotBundle {
  const root = store.get(rootId);
  if (!root) throw new Error(`No bot "${rootId}"`);
  const bots: BotBundleEntry[] = [];
  const collect = (id: string): void => {
    const m = store.get(id);
    if (!m) return;
    const entry: BotBundleEntry = {
      id: m.id,
      name: m.name,
      description: m.description,
      manifest: sanitizeManifest(m),
      persona: store.readPersona(id),
      permissions: store.ensurePermissions(id),
    };
    if (opts.withSkills) entry.skills = collectSkills(store.skillsDir(id));
    bots.push(entry);
    for (const crew of store.crewOf(id)) collect(crew.id);
  };
  collect(rootId);
  return {
    format: BOT_BUNDLE_FORMAT,
    version: BOT_BUNDLE_VERSION,
    kind: bots.length > 1 ? 'fleet' : 'bot',
    root: rootId,
    exportedAt: new Date().toISOString(),
    bots,
  };
}

/**
 * Recreate bots from a bundle into this store. Every imported bot starts
 * DISABLED (fail-closed: a shared bundle must never begin firing cron
 * routines or spending tokens unattended — enable consciously with
 * /bots enable). Existing ids are skipped (never overwritten) unless
 * opts.overwrite refreshes persona/permissions in place. Fleet nesting
 * falls out of the manifests' parent fields via the store's physical
 * layout; imports of a single crew bot arrive parentless (solo).
 */
export function importBotBundle(
  store: BotStore,
  bundle: BotBundle,
  opts: { overwrite?: boolean } = {},
): BundleImportReport {
  assertValidBundle(bundle);
  const report: BundleImportReport = { created: [], skipped: [] };
  // Parents before children: our builder already emits lead-first; enforce
  // it defensively so a hand-built bundle cannot create a child before its
  // parent's directory exists.
  for (const entry of orderedRootsFirst(bundle.bots, bundle.root)) {
    const exists = store.exists(entry.id);
    if (exists && !opts.overwrite) {
      report.skipped.push({ id: entry.id, reason: 'already exists (use overwrite to refresh persona/permissions)' });
      continue;
    }
    if (!exists) {
      store.create({
        id: entry.id,
        name: entry.name,
        description: entry.description,
        persona: entry.persona,
        manifest: { ...entry.manifest, enabled: false } as Partial<BotManifest>,
      });
    } else if (opts.overwrite) {
      store.update(entry.id, m => {
        m.name = entry.name;
        m.description = entry.description;
        for (const [k, v] of Object.entries(entry.manifest)) {
          if (k === 'enabled' || k === 'id' || k === 'name') continue;
          (m as any)[k] = v;
        }
        m.enabled = store.get(entry.id)?.enabled ?? false;
      });
    }
    store.writePersona(entry.id, entry.persona);
    store.writePermissions(entry.id, entry.permissions);
    for (const [relPath, content] of Object.entries(entry.skills ?? {})) {
      const target = join(store.skillsDir(entry.id), relPath);
      mkdirSync(resolve(target, '..'), { recursive: true });
      writeFileSync(target, content, 'utf-8');
    }
    if (!exists) report.created.push(entry.id);
    else report.skipped.push({ id: entry.id, reason: 'existing bot refreshed (overwrite)' });
  }
  logger.info({ root: bundle.root, created: report.created.length, skipped: report.skipped.length }, 'Bot bundle imported');
  return report;
}

/** Structural validation — never throws on content, only on shape. */
function assertValidBundle(bundle: BotBundle): void {
  if (!bundle || bundle.format !== BOT_BUNDLE_FORMAT) {
    throw new Error(`Not a Mercury bot bundle (expected format "${BOT_BUNDLE_FORMAT}")`);
  }
  if (bundle.version !== BOT_BUNDLE_VERSION) {
    throw new Error(`Unsupported bundle version ${bundle.version} (this Mercury reads v${BOT_BUNDLE_VERSION})`);
  }
  if (!Array.isArray(bundle.bots) || bundle.bots.length === 0 || !bundle.bots.some(b => b.id === bundle.root)) {
    throw new Error('Bundle is missing its bots or its root entry');
  }
}

function sanitizeManifest(m: BotManifest): Record<string, unknown> {
  const out: Record<string, unknown> = { ...m } as any;
  for (const field of VOLATILE_MANIFEST_FIELDS) delete out[field];
  // Permissions travel in their own block (single source of truth) — the
  // legacy manifest copy is dropped so the file, not bot.yaml, decides.
  delete out.tools;
  return out;
}

/** Defensive topological order: every bot after its bundle parent (cycles tolerated → appended, then rejected by save's cycle guard). */
function orderedRootsFirst(entries: BotBundleEntry[], _root: string): BotBundleEntry[] {
  const pending = new Set(entries.map(e => e.id));
  const out: BotBundleEntry[] = [];
  const emit = (entry: BotBundleEntry): void => {
    if (!pending.has(entry.id)) return;
    pending.delete(entry.id);
    out.push(entry);
    const parent = entry.manifest.parent as string | undefined;
    if (parent) {
      const lead = entries.find(e => e.id === parent);
      if (lead) emit(lead);
    }
  };
  for (const entry of entries) emit(entry);
  for (const id of pending) out.push(entries.find(e => e.id === id)!);
  return out;
}

/** Default export location: ~/.mercury/exports/<id>.bot.json */
export function defaultBundlePath(rootId: string): string {
  const dir = join(getMercuryHome(), 'exports');
  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
  return join(dir, `${rootId}.bot.json`);
}

export function writeBundle(bundle: BotBundle, outPath?: string): string {
  const path = outPath ?? defaultBundlePath(bundle.root);
  mkdirSync(resolve(path, '..'), { recursive: true });
  writeFileSync(path, JSON.stringify(bundle, null, 2), 'utf-8');
  return path;
}

export function readBundle(path: string): BotBundle {
  return JSON.parse(readFileSync(path, 'utf-8')) as BotBundle;
}

/** Recurse a skills dir into {relativePath: textContent} (md/json/yaml only). */
function collectSkills(dir: string, prefix = ''): Record<string, string> {
  const out: Record<string, string> = {};
  if (!existsSync(dir)) return out;
  for (const entry of readdirSafe(dir)) {
    if (entry.isDirectory() && !entry.name.startsWith('.') && !entry.name.startsWith('_')) {
      Object.assign(out, collectSkills(join(dir, entry.name), join(prefix, entry.name)));
    } else if (entry.isFile() && /\.(md|json|ya?ml|txt)$/i.test(entry.name) && entry.name !== '.env') {
      try {
        const content = readFileSync(join(dir, entry.name), 'utf-8');
        if (content.length <= 256 * 1024) out[join(prefix, entry.name)] = content;
      } catch { /* unreadable skill file → skipped */ }
    }
  }
  return out;
}

function readdirSafe(dir: string): Array<{ name: string; isDirectory(): boolean; isFile(): boolean }> {
  try {
    return readdirSync(dir, { withFileTypes: true }) as any;
  } catch {
    return [];
  }
}