Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.4 KB
Raw Blame
import { describe, expect, test } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { withEnv } from './helpers/with-env.ts';
import {
  canSelfUpdate,
  clearSnooze,
  clearUpdateCache,
  decideSelfUpgrade,
  formatMarker,
  gateOnTargetRuntime,
  isCacheFresh,
  isSnoozeActive,
  parseMarker,
  readSnooze,
  readUpdateCache,
  reconcileBreadcrumb,
  resolveSelfUpgradeMode,
  snoozeDurationMs,
  writeSnooze,
  writeUpdateCache,
  type DecideSelfUpgradeInputs,
  type SelfUpgradeAction,
  type SelfUpgradeState,
} from '../src/core/self-upgrade.ts';
import type { HostBun, TargetFloor } from '../src/core/bun-floor.ts';

function baseInputs(over: Partial<DecideSelfUpgradeInputs> = {}): DecideSelfUpgradeInputs {
  return {
    mode: 'notify',
    currentVersion: '0.42.0',
    latestVersion: '0.43.0',
    failedVersions: [],
    channel: 'invocation',
    ...over,
  };
}

async function withTmpHome<T>(fn: () => T | Promise<T>): Promise<T> {
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-selfupgrade-'));
  try {
    return await withEnv({ GBRAIN_HOME: dir, GBRAIN_SELF_UPGRADE_MODE: undefined }, fn);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

describe('decideSelfUpgrade — pure branches', () => {
  test('mode=off short-circuits', () => {
    expect(decideSelfUpgrade(baseInputs({ mode: 'off' })).action).toBe('off');
  });

  test('null/invalid latest → not_behind (fail-open)', () => {
    expect(decideSelfUpgrade(baseInputs({ latestVersion: null })).action).toBe('not_behind');
    expect(decideSelfUpgrade(baseInputs({ latestVersion: 'garbage' })).action).toBe('not_behind');
    expect(decideSelfUpgrade(baseInputs({ latestVersion: 'rm -rf /' })).action).toBe('not_behind');
  });

  test('equal version → not_behind', () => {
    expect(decideSelfUpgrade(baseInputs({ latestVersion: '0.42.0' })).action).toBe('not_behind');
  });

  test('latest < current → downgrade_or_yanked (never acts)', () => {
    const d = decideSelfUpgrade(baseInputs({ currentVersion: '0.43.0', latestVersion: '0.42.0' }));
    expect(d.action).toBe('downgrade_or_yanked');
  });

  test('patch and micro releases → behind', () => {
    expect(decideSelfUpgrade(baseInputs({ currentVersion: '0.42.0', latestVersion: '0.42.1' })).action).toBe('notify');
    expect(decideSelfUpgrade(baseInputs({ currentVersion: '0.42.3.0', latestVersion: '0.42.3.1' })).action).toBe('notify');
  });

  test('minor bump → behind', () => {
    expect(decideSelfUpgrade(baseInputs({ currentVersion: '0.42.0', latestVersion: '0.43.0' })).action).toBe('notify');
  });

  test('major bump → behind', () => {
    expect(decideSelfUpgrade(baseInputs({ currentVersion: '0.42.0', latestVersion: '1.0.0' })).action).toBe('notify');
  });

  test('known-bad latest → known_bad (no retry)', () => {
    const d = decideSelfUpgrade(baseInputs({ failedVersions: ['0.43.0'] }));
    expect(d.action).toBe('known_bad');
  });

  test('invocation channel: snoozed → throttled', () => {
    expect(decideSelfUpgrade(baseInputs({ snoozed: true })).action).toBe('throttled');
  });

  test('invocation channel: not snoozed → notify', () => {
    expect(decideSelfUpgrade(baseInputs({ snoozed: false })).action).toBe('notify');
  });

  describe('autopilot channel gates', () => {
    const auto = (over: Partial<DecideSelfUpgradeInputs> = {}) =>
      decideSelfUpgrade(
        baseInputs({
          mode: 'auto',
          channel: 'autopilot',
          idle: true,
          inQuietHours: true,
          canSelfUpdate: true,
          throttledByInterval: false,
          ...over,
        }),
      );

    test('all gates pass → apply', () => {
      expect(auto().action).toBe('apply');
    });
    test('throttledByInterval → throttled', () => {
      expect(auto({ throttledByInterval: true }).action).toBe('throttled');
    });
    test('not idle → busy', () => {
      expect(auto({ idle: false }).action).toBe('busy');
    });
    test('outside quiet hours → outside_quiet_hours', () => {
      expect(auto({ inQuietHours: false }).action).toBe('outside_quiet_hours');
    });
    test('cannot self-update → unsupported_install', () => {
      expect(auto({ canSelfUpdate: false }).action).toBe('unsupported_install');
    });
    test('gate order: known_bad beats idle/quiet gates', () => {
      expect(auto({ failedVersions: ['0.43.0'], idle: false }).action).toBe('known_bad');
    });

    test('#5855: an apply is held when the target Bun floor is above the host Bun, or either is unknown', () => {
      const bun = (version: string): HostBun => ({ label: 'bun on PATH', path: '/opt/bun', version });
      const floor = (f: string): TargetFloor => ({ ok: true, floor: f, version: null });
      const cases: Array<{ target: TargetFloor; host: HostBun | null; action: SelfUpgradeAction; reason?: string[] }> = [
        { target: floor('1.4.0'), host: bun('1.4.2'), action: 'apply' },
        { target: floor('1.4.0'), host: bun('1.4.0'), action: 'apply' },
        { target: floor('1.4.0'), host: bun('1.4.0+5a1b2c3'), action: 'apply' },
        { target: floor('1.4.0'), host: bun('1.5.0-canary.2'), action: 'apply' },
        { target: floor('1.4.0'), host: bun('1.4.0-canary.9'), action: 'unsupported_runtime', reason: ['gbrain 0.43.0 requires Bun >=1.4.0', 'bun on PATH is 1.4.0-canary.9'] },
        { target: floor('1.4.0'), host: bun('1.3.14'), action: 'unsupported_runtime', reason: ['gbrain 0.43.0 requires Bun >=1.4.0', 'bun on PATH is 1.3.14', 'Fix: bun upgrade, then gbrain upgrade'] },
        { target: { ok: false, failedRead: '`git fetch` in the source clone failed' }, host: bun('1.4.2'), action: 'unsupported_runtime', reason: ['Could not read the Bun floor of gbrain 0.43.0', 'The next quiet-hours tick retries'] },
        { target: floor('1.4.0'), host: null, action: 'unsupported_runtime', reason: ['could not run `bun --version` on PATH'] },
      ];
      for (const c of cases) {
        const d = gateOnTargetRuntime(auto(), c.target, c.host);
        expect(d.action, JSON.stringify(c)).toBe(c.action);
        expect(d.latest).toBe('0.43.0');
        for (const fragment of c.reason ?? []) expect(d.reason).toContain(fragment);
        expect(d.reason).not.toContain('/opt/bun');
      }
    });

    test('#5855: the runtime gate leaves a non-apply decision unchanged', () => {
      const busy = auto({ idle: false });
      expect(gateOnTargetRuntime(busy, { ok: true, floor: '9.0.0', version: null }, null)).toEqual(busy);
    });
  });
});

describe('canSelfUpdate', () => {
  test('bun / bun-link always self-update', () => {
    for (const m of ['bun', 'bun-link']) {
      expect(canSelfUpdate(m, 'darwin', 'arm64')).toBe(true);
      expect(canSelfUpdate(m, 'win32', 'x64')).toBe(true);
    }
  });
  test('#8464: clawhub is never an unattended upgrade path', () => {
    expect(canSelfUpdate('clawhub', 'darwin', 'arm64')).toBe(false);
    expect(canSelfUpdate('clawhub', 'linux', 'x64')).toBe(false);
  });
  test('binary self-updates only where a release asset exists (darwin-arm64, linux-x64)', () => {
    expect(canSelfUpdate('binary', 'darwin', 'arm64')).toBe(true);
    expect(canSelfUpdate('binary', 'linux', 'x64')).toBe(true);
    expect(canSelfUpdate('binary', 'darwin', 'x64')).toBe(false); // no asset published
    expect(canSelfUpdate('binary', 'linux', 'arm64')).toBe(false); // no asset published
    expect(canSelfUpdate('binary', 'win32', 'x64')).toBe(false);
  });
  test('unknown method cannot self-update', () => {
    expect(canSelfUpdate('unknown', 'darwin', 'arm64')).toBe(false);
  });
});

describe('marker grammar', () => {
  test('round-trips up_to_date and upgrade_available', () => {
    const a = { kind: 'up_to_date' as const, current: '0.42.0' };
    expect(parseMarker(formatMarker(a))).toEqual(a);
    const b = { kind: 'upgrade_available' as const, current: '0.42.0', latest: '0.43.0' };
    expect(parseMarker(formatMarker(b))).toEqual(b);
  });
  test('rejects forged / malformed markers', () => {
    expect(parseMarker('UPGRADE_AVAILABLE 0.42.0 $(rm -rf /)')).toBeNull();
    expect(parseMarker('UPGRADE_AVAILABLE 0.42.0')).toBeNull();
    expect(parseMarker('EVIL 0.42.0 0.43.0')).toBeNull();
    expect(parseMarker('UP_TO_DATE not-a-version')).toBeNull();
    expect(parseMarker('')).toBeNull();
  });
});

describe('snooze', () => {
  test('escalating durations cap at 7d', () => {
    expect(snoozeDurationMs(1)).toBe(24 * 3600 * 1000);
    expect(snoozeDurationMs(2)).toBe(48 * 3600 * 1000);
    expect(snoozeDurationMs(3)).toBe(7 * 24 * 3600 * 1000);
    expect(snoozeDurationMs(99)).toBe(7 * 24 * 3600 * 1000);
  });
  test('isSnoozeActive: time-based, holds across newer releases, ends at its expiry or on a rollback below the snoozed version', () => {
    const now = 1_000_000_000_000;
    const rec = { version: '0.43.0', level: 1, ts: now, until: now + 24 * 3600 * 1000 };
    expect(isSnoozeActive(rec, '0.43.0', now + 1000)).toBe(true);
    expect(isSnoozeActive(rec, '0.44.0', now + 1000)).toBe(true); // a newer release does not end it
    expect(isSnoozeActive(rec, '0.99.0', now + 23 * 3600 * 1000)).toBe(true);
    expect(isSnoozeActive(rec, '0.43.0', now + 25 * 3600 * 1000)).toBe(false); // expired
    expect(isSnoozeActive(rec, '0.42.0', now + 1000)).toBe(false); // rolled back below the snoozed version
    expect(isSnoozeActive(null, '0.43.0', now)).toBe(false);
  });
  test('writeSnooze escalates per channel whatever version is offered (24h, 48h, 7d), atomically; clearSnooze clears every channel', async () => {
    await withTmpHome(() => {
      const now = 1_700_000_000_000;
      const h = 3600 * 1000;
      expect(writeSnooze('0.43.0', now, 'alpha')).toMatchObject({ level: 1, until: now + 24 * h });
      expect(writeSnooze('0.44.0', now, 'alpha')).toMatchObject({ level: 2, until: now + 48 * h });
      expect(writeSnooze('0.45.0', now, 'alpha')).toMatchObject({ level: 3, until: now + 7 * 24 * h });
      expect(writeSnooze('0.46.0', now, 'alpha').level).toBe(3); // capped
      expect(writeSnooze('0.43.0', now, 'stable').level).toBe(1); // channels are independent
      expect(readSnooze('alpha')).toMatchObject({ version: '0.46.0', level: 3 });
      expect(readSnooze('stable')).toMatchObject({ version: '0.43.0', level: 1 });
      clearSnooze();
      expect(readSnooze('alpha')).toBeNull();
      expect(readSnooze('stable')).toBeNull();
    });
  });
  test('corrupt snooze file → null', async () => {
    await withTmpHome(async () => {
      const { writeFileSync, mkdirSync } = await import('node:fs');
      const { gbrainPath } = await import('../src/core/config.ts');
      mkdirSync(gbrainPath(), { recursive: true });
      writeFileSync(gbrainPath('update-snoozed'), 'garbage not three fields here');
      expect(readSnooze()).toBeNull();
      writeFileSync(gbrainPath('update-snoozed.stable.json'), '{"version":"0.43.0","level":"x"}');
      expect(readSnooze('stable')).toBeNull();
    });
  });
});

describe('cache', () => {
  test('write → read round-trip, atomic, fresh check', async () => {
    await withTmpHome(() => {
      writeUpdateCache({ kind: 'upgrade_available', current: '0.42.0', latest: '0.43.0' });
      const entry = readUpdateCache();
      expect(entry?.marker).toEqual({ kind: 'upgrade_available', current: '0.42.0', latest: '0.43.0' });
      expect(isCacheFresh(entry!, entry!.mtimeMs + 1000)).toBe(true);
      expect(isCacheFresh(entry!, entry!.mtimeMs + 13 * 3600 * 1000)).toBe(false); // > 12h
      clearUpdateCache();
      expect(readUpdateCache()).toBeNull();
    });
  });
  test('up_to_date uses the 60min TTL', async () => {
    await withTmpHome(() => {
      writeUpdateCache({ kind: 'up_to_date', current: '0.42.0' });
      const entry = readUpdateCache()!;
      expect(isCacheFresh(entry, entry.mtimeMs + 59 * 60 * 1000)).toBe(true);
      expect(isCacheFresh(entry, entry.mtimeMs + 61 * 60 * 1000)).toBe(false);
    });
  });
  test('corrupt cache file → null (fail-open)', async () => {
    await withTmpHome(async () => {
      const { writeFileSync, mkdirSync } = await import('node:fs');
      const { gbrainPath } = await import('../src/core/config.ts');
      mkdirSync(gbrainPath(), { recursive: true });
      writeFileSync(gbrainPath('last-update-check'), 'EVIL not a marker');
      expect(readUpdateCache()).toBeNull();
    });
  });
});

describe('writeJustUpgraded', () => {
  test('writes the from-version breadcrumb the CLI startup hook reads', async () => {
    await withTmpHome(async () => {
      const { writeJustUpgraded, justUpgradedPath } = await import('../src/core/self-upgrade.ts');
      const { readFileSync } = await import('node:fs');
      writeJustUpgraded('0.42.0');
      expect(readFileSync(justUpgradedPath(), 'utf8').trim()).toBe('0.42.0');
    });
  });
});

describe('reconcileBreadcrumb', () => {
  test('no breadcrumb → no transition', () => {
    expect(reconcileBreadcrumb(undefined, '0.42.0').transition).toBeNull();
    expect(reconcileBreadcrumb({}, '0.42.0').transition).toBeNull();
  });
  test('breadcrumb matches running version → applied, breadcrumb cleared, last_applied set', () => {
    const r = reconcileBreadcrumb({ attempting_version: '0.43.0' }, '0.43.0');
    expect(r.transition).toBe('applied');
    expect(r.state.attempting_version).toBeUndefined();
    expect(r.state.last_applied_version).toBe('0.43.0');
  });
  test('breadcrumb != running version → failed, recorded known-bad, breadcrumb cleared', () => {
    const r = reconcileBreadcrumb({ attempting_version: '0.43.0' }, '0.42.0');
    expect(r.transition).toBe('failed');
    expect(r.state.attempting_version).toBeUndefined();
    expect(r.state.failed_versions).toContain('0.43.0');
  });
  test('failed dedups into existing failed_versions', () => {
    const r = reconcileBreadcrumb({ attempting_version: '0.43.0', failed_versions: ['0.43.0', '0.41.0'] }, '0.42.0');
    expect(r.state.failed_versions?.filter((v) => v === '0.43.0').length).toBe(1);
  });
  test('unparseable running version → failed (no ordering to trust)', () => {
    const r = reconcileBreadcrumb({ attempting_version: '0.43.0' }, 'dev');
    expect(r.transition).toBe('failed');
    expect(r.state.failed_versions).toEqual(['0.43.0']);
  });
  // #5813: the swap installs whatever is current at swap time (git pull, bun
  // update, the release latest-stable names), so the relaunched binary can be NEWER than the
  // version the breadcrumb recorded from the update cache.
  const appliedCases: Array<{ name: string; su: SelfUpgradeState; running: string; failed: string[] | undefined }> = [
    { name: 'running newer than attempted', su: { attempting_version: '0.60.22.0' }, running: '0.60.25.0', failed: undefined },
    {
      name: 'prunes known-bad entries at or below the running version',
      su: { attempting_version: '0.60.22.0', failed_versions: ['0.59.2.0', '0.60.25.0', '0.60.30.0'] },
      running: '0.60.25.0',
      failed: ['0.60.30.0'],
    },
    {
      name: 'exact match prunes too and keeps unparseable entries',
      su: { attempting_version: '0.43.0', failed_versions: ['0.41.0', 'not-a-version'] },
      running: '0.43.0',
      failed: ['not-a-version'],
    },
    {
      name: 'pruning every entry drops the key',
      su: { attempting_version: '0.60.22.0', failed_versions: ['0.59.2.0', '0.60.8.0'] },
      running: '0.60.25.0',
      failed: undefined,
    },
  ];
  for (const c of appliedCases) {
    test(`applied: ${c.name}`, () => {
      const r = reconcileBreadcrumb(c.su, c.running);
      expect(r.transition).toBe('applied');
      expect(r.state.attempting_version).toBeUndefined();
      expect(r.state.last_applied_version).toBe(c.running);
      expect(r.state.failed_versions).toEqual(c.failed);
    });
  }
});

describe('resolveSelfUpgradeMode', () => {
  test('defaults to notify', async () => {
    await withEnv({ GBRAIN_SELF_UPGRADE_MODE: undefined }, () => {
      expect(resolveSelfUpgradeMode(null)).toBe('notify');
      expect(resolveSelfUpgradeMode({})).toBe('notify');
      expect(resolveSelfUpgradeMode({ self_upgrade: { mode: 'bogus' } })).toBe('notify');
    });
  });
  test('config plane honored', async () => {
    await withEnv({ GBRAIN_SELF_UPGRADE_MODE: undefined }, () => {
      expect(resolveSelfUpgradeMode({ self_upgrade: { mode: 'auto' } })).toBe('auto');
      expect(resolveSelfUpgradeMode({ self_upgrade: { mode: 'off' } })).toBe('off');
    });
  });
  test('env overrides config', async () => {
    await withEnv({ GBRAIN_SELF_UPGRADE_MODE: 'off' }, () => {
      expect(resolveSelfUpgradeMode({ self_upgrade: { mode: 'auto' } })).toBe('off');
    });
  });
});