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.

14.8 KB
Raw Blame
/**
 * On-disk layout and state for plugins.
 *
 *   ~/.mercury/plugins/
 *     state.json              which plugins are installed / enabled (atomic writes)
 *     catalog-cache.json      last catalog fetched, so /plugins works offline
 *     .lock                   install/uninstall lock (CLI and daemon share it)
 *     .staging/               scratch space for installs; never read by the loader
 *     <id>/
 *       versions/<version>/   the installed package (current + one previous)
 *       data/                 plugin-owned data, kept across updates
 *       settings.json         owner settings, kept across updates
 */
import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import semver from 'semver';
import { AsyncLocalStorage } from 'node:async_hooks';
import { getMercuryHome } from '../utils/config.js';
import { logger } from '../utils/logger.js';
import {
  MANIFEST_VERSION, PLUGIN_API_VERSION, PLUGIN_ID_RE,
  type PluginManifest, type PluginsState, type PlatformKey,
} from './types.js';

export function pluginsRoot(): string {
  return join(getMercuryHome(), 'plugins');
}
export function pluginDir(id: string): string {
  assertId(id);
  return join(pluginsRoot(), id);
}
export function pluginVersionDir(id: string, version: string): string {
  return join(pluginDir(id), 'versions', version);
}
export function pluginDataDir(id: string): string {
  return join(pluginDir(id), 'data');
}
export function pluginSettingsPath(id: string): string {
  return join(pluginDir(id), 'settings.json');
}
export function stagingRoot(): string {
  return join(pluginsRoot(), '.staging');
}

export function assertId(id: string): void {
  if (!PLUGIN_ID_RE.test(id)) throw new Error(`Invalid plugin id "${id}"`);
}

// ── platform and compatibility ─────────────────────────────────────────────

export function currentPlatform(): PlatformKey {
  const os = process.platform === 'android' ? 'android' : process.platform;
  return `${os}-${process.arch}` as PlatformKey;
}

/** Mercury's own version: stamped into compiled builds, else package.json. */
export function mercuryVersion(): string {
  const stamped = (globalThis as { __MERCURY_VERSION__?: string }).__MERCURY_VERSION__;
  if (stamped) return stamped;
  return process.env.MERCURY_VERSION_OVERRIDE ?? packageVersion();
}

let cachedPkgVersion: string | null = null;
function packageVersion(): string {
  if (cachedPkgVersion) return cachedPkgVersion;
  let here = process.cwd();
  try { here = dirname(fileURLToPath(import.meta.url)); } catch { /* compiled binary: virtual path */ }
  const candidates = [join(here, '..', '..', 'package.json'), join(here, '..', 'package.json'), join(process.cwd(), 'package.json')];
  for (const p of candidates) {
    try {
      const pkg = JSON.parse(readFileSync(p, 'utf8')) as { name?: string; version?: string };
      if (pkg.name === '@cosmicstack/mercury-agent' && pkg.version) return (cachedPkgVersion = pkg.version);
    } catch { /* next */ }
  }
  return (cachedPkgVersion = '0.0.0');
}

/**
 * Why a manifest can't run here, or null if it can. Pre-release Mercury
 * builds (dev channel) are matched as their release version.
 */
export function incompatibility(manifest: Pick<PluginManifest, 'engines' | 'platforms'> & { manifestVersion?: number }): string | null {
  if (manifest.manifestVersion !== undefined && manifest.manifestVersion !== MANIFEST_VERSION) {
    return `manifest version ${manifest.manifestVersion} is not supported (this Mercury reads version ${MANIFEST_VERSION})`;
  }
  const mv = semver.coerce(mercuryVersion())?.version ?? '0.0.0';
  if (!semver.satisfies(mv, manifest.engines.mercury, { includePrerelease: true })) {
    return `needs Mercury ${manifest.engines.mercury}, this is ${mv}`;
  }
  const api = manifest.engines.pluginApi ?? '^1.0.0';
  if (!semver.satisfies(PLUGIN_API_VERSION, api)) {
    return `needs plugin API ${api}, this Mercury provides ${PLUGIN_API_VERSION}`;
  }
  if (manifest.platforms && !manifest.platforms.includes(currentPlatform())) {
    return `not available for ${currentPlatform()} (supports ${manifest.platforms.join(', ')})`;
  }
  return null;
}

// ── state ─────────────────────────────────────────────────────────────────

function emptyState(): PluginsState {
  return { stateVersion: 1, plugins: {}, boot: { inProgress: false, failedBoots: 0 } };
}

function statePath(): string {
  return join(pluginsRoot(), 'state.json');
}

/** Read state.json. A missing or corrupt file never throws: corrupt files are set aside. */
export function readState(): PluginsState {
  const path = statePath();
  if (!existsSync(path)) return emptyState();
  try {
    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<PluginsState>;
    if (raw.stateVersion !== 1 || typeof raw.plugins !== 'object' || raw.plugins === null) throw new Error('unexpected shape');
    const plugins: PluginsState['plugins'] = {};
    for (const [id, entry] of Object.entries(raw.plugins)) {
      if (PLUGIN_ID_RE.test(id) && entry && typeof entry.version === 'string') plugins[id] = entry;
    }
    return {
      stateVersion: 1,
      plugins,
      boot: {
        inProgress: raw.boot?.inProgress === true,
        failedBoots: Number.isInteger(raw.boot?.failedBoots) ? raw.boot!.failedBoots : 0,
        lastChange: raw.boot?.lastChange,
      },
    };
  } catch (err) {
    const aside = `${path}.corrupt-${Date.now()}`;
    try { renameSync(path, aside); } catch { /* ignore */ }
    logger.warn({ err, aside }, 'Plugin state was unreadable; set it aside and started empty (no plugins load)');
    return emptyState();
  }
}

/** Atomic write: temp file + rename, so a crash mid-write can't corrupt state. */
export function writeState(state: PluginsState): void {
  mkdirSync(pluginsRoot(), { recursive: true });
  writeJsonAtomic(statePath(), state);
}

export function writeJsonAtomic(path: string, data: unknown): void {
  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
  writeFileSync(tmp, JSON.stringify(data, null, 2), { encoding: 'utf8', mode: 0o600 });
  renameSync(tmp, path);
}

/** Read-modify-write under the install lock. */
export async function updateState(mutate: (s: PluginsState) => void): Promise<PluginsState> {
  return withLock(async () => {
    const s = readState();
    mutate(s);
    writeState(s);
    return s;
  });
}

// ── lock ──────────────────────────────────────────────────────────────────

const LOCK_STALE_MS = 10 * 60 * 1000;

function lockPath(): string {
  return join(pluginsRoot(), '.lock');
}

function pidAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch (err) {
    return (err as NodeJS.ErrnoException).code === 'EPERM';
  }
}

/**
 * Lock for anything that changes plugins on disk.
 * - Across processes: an exclusive lock file (the daemon and a
 *   `mercury plugins …` CLI call can run at the same time). Stale locks
 *   (dead pid, or older than 10 minutes) are taken over.
 * - Within a process: a queue, so concurrent async callers run one at a time.
 * - Re-entrant only for genuinely nested calls (same async context), via
 *   AsyncLocalStorage, never for unrelated concurrent work.
 */
const lockContext = new AsyncLocalStorage<boolean>();
let lockQueue: Promise<unknown> = Promise.resolve();

export async function withLock<T>(fn: () => Promise<T>, timeoutMs = 30_000): Promise<T> {
  if (lockContext.getStore()) return fn();
  const run = async (): Promise<T> => {
    await acquireFileLock(timeoutMs);
    try {
      return await lockContext.run(true, fn);
    } finally {
      try { rmSync(lockPath(), { force: true }); } catch { /* ignore */ }
    }
  };
  const result = lockQueue.then(run, run);
  lockQueue = result.catch(() => {});
  return result;
}

async function acquireFileLock(timeoutMs: number): Promise<void> {
  mkdirSync(pluginsRoot(), { recursive: true });
  const path = lockPath();
  const started = Date.now();
  for (;;) {
    try {
      const fd = openSync(path, 'wx', 0o600);
      writeSync(fd, String(process.pid));
      closeSync(fd);
      return;
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
      let stale = false;
      try {
        const pid = Number(readFileSync(path, 'utf8').trim());
        const age = Date.now() - statSync(path).mtimeMs;
        stale = !Number.isInteger(pid) || pid <= 0 || !pidAlive(pid) || age > LOCK_STALE_MS;
      } catch {
        stale = true;
      }
      if (stale) {
        try { rmSync(path, { force: true }); } catch { /* raced */ }
        continue;
      }
      if (Date.now() - started > timeoutMs) throw new Error('Another plugin install or uninstall is in progress. Try again in a moment.');
      await new Promise((r) => setTimeout(r, 150));
    }
  }
}

// ── settings ──────────────────────────────────────────────────────────────

interface SettingsFile {
  settingsVersion: number;
  values: Record<string, unknown>;
}

function readSettingsFile(path: string): SettingsFile | null {
  try {
    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<SettingsFile>;
    const values = raw.values && typeof raw.values === 'object' && !Array.isArray(raw.values) ? raw.values : {};
    const v = Number.isInteger(raw.settingsVersion) && (raw.settingsVersion as number) >= 1 ? (raw.settingsVersion as number) : 1;
    return { settingsVersion: v, values };
  } catch {
    return null;
  }
}

export function readSettings(id: string): Record<string, unknown> {
  return readSettingsFile(pluginSettingsPath(id))?.values ?? {};
}

/** Saved settings from `from` brought up to the manifest's settings version. */
export function migrateSettingValues(manifest: PluginManifest, values: Record<string, unknown>, from: number): Record<string, unknown> {
  const out = { ...values };
  for (const step of manifest.settings?.migrations ?? []) {
    if (step.to <= from) continue;
    for (const [oldKey, newKey] of Object.entries(step.rename)) {
      if (oldKey in out) {
        if (!(newKey in out)) out[newKey] = out[oldKey];
        delete out[oldKey];
      }
    }
    for (const key of step.remove) delete out[key];
    for (const [key, map] of Object.entries(step.mapValues)) {
      const v = out[key];
      if ((typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') && Object.prototype.hasOwnProperty.call(map, String(v))) {
        out[key] = map[String(v)];
      }
    }
  }
  return out;
}

/**
 * Bring settings.json up to this version's settings version, once, before
 * the plugin starts. The file being replaced is kept as
 * `settings.v<N>.json`, so a rollback to the older plugin finds its own
 * settings again instead of values it doesn't understand.
 */
export function migrateSettings(manifest: PluginManifest): { from: number; to: number } | null {
  const target = manifest.settings?.version ?? 1;
  const path = pluginSettingsPath(manifest.id);
  const saved = readSettingsFile(path);
  if (!saved || saved.settingsVersion === target) return null;
  const backup = (v: number) => join(pluginDir(manifest.id), `settings.v${v}.json`);
  writeJsonAtomic(backup(saved.settingsVersion), saved);
  if (saved.settingsVersion > target) {
    // Rolled back to an older plugin: restore that version's saved settings if we have them.
    const older = readSettingsFile(backup(target));
    writeJsonAtomic(path, older && older.settingsVersion === target ? older : { settingsVersion: target, values: {} });
  } else {
    writeJsonAtomic(path, { settingsVersion: target, values: migrateSettingValues(manifest, saved.values, saved.settingsVersion) });
  }
  return { from: saved.settingsVersion, to: target };
}

/**
 * Settings with defaults filled in and values coerced to the declared types.
 * Unknown keys are dropped, so a plugin never sees a value its manifest
 * doesn't describe. Older saved versions are migrated in memory first.
 */
export function resolvedSettings(manifest: PluginManifest): Record<string, unknown> {
  const fields = manifest.settings?.fields ?? {};
  const file = readSettingsFile(pluginSettingsPath(manifest.id));
  const target = manifest.settings?.version ?? 1;
  const saved = !file ? {} : file.settingsVersion < target ? migrateSettingValues(manifest, file.values, file.settingsVersion) : file.settingsVersion > target ? {} : file.values;
  const out: Record<string, unknown> = {};
  for (const [key, field] of Object.entries(fields)) {
    if (field.type === 'secret') continue; // keys live in the key store, not settings
    const v = saved[key];
    let value: unknown = field.default;
    if (field.type === 'boolean' && typeof v === 'boolean') value = v;
    else if (field.type === 'number' && typeof v === 'number' && Number.isFinite(v)) value = v;
    else if (field.type === 'string' && typeof v === 'string') value = v;
    else if (field.type === 'enum' && typeof v === 'string' && field.options?.includes(v)) value = v;
    if (value !== undefined) out[key] = value;
  }
  return out;
}

export function writeSettings(id: string, values: Record<string, unknown>, settingsVersion: number): void {
  mkdirSync(pluginDir(id), { recursive: true });
  writeJsonAtomic(pluginSettingsPath(id), { settingsVersion, values });
}

// ── key store ─────────────────────────────────────────────────────────────

/**
 * API keys plugin settings ask for (type "secret"), e.g. an ElevenLabs key
 * for WhatsApp voice. One owner-only file for every plugin; each plugin only
 * ever receives the names it declares in permissions.secrets.
 */
export function pluginKeysPath(): string {
  return join(getMercuryHome(), 'plugin-keys.json');
}

export function readPluginKeys(): Record<string, string> {
  try {
    const raw = JSON.parse(readFileSync(pluginKeysPath(), 'utf8')) as Record<string, unknown>;
    return Object.fromEntries(Object.entries(raw).filter((e): e is [string, string] => typeof e[1] === 'string' && e[1].length > 0));
  } catch {
    return {};
  }
}

export function setPluginKey(name: string, value: string | null): void {
  const keys = readPluginKeys();
  if (value) keys[name] = value;
  else delete keys[name];
  writeJsonAtomic(pluginKeysPath(), keys);
}

/** A declared secret: Mercury's environment first (~/.mercury/.env), then the key store. */
export function secretValue(name: string): string | undefined {
  return process.env[name] || readPluginKeys()[name] || undefined;
}