Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.5 KB
Raw Blame
/**
 * The stable release channel on the client side (GBRA-175, GBRA-224 W1).
 *
 * A stable release is accepted only with evidence. scripts/promote-stable.ts moves the annotated `stable` tag and, in
 * the same atomic push, commits the evidence record (`stable.json`) to the `stable-record` branch, so a client reads it
 * at a raw URL with no API call and no git. The record names the version, its commit and tree, the soak run (and,
 * from MATRIX_REQUIRED_FROM on, the upgrade-matrix run) and the `known_bad` list of withdrawn versions. A lookup
 * fails one of three ways, each a typed code: `stable_missing` (nothing promoted), `stable_invalid` (a record or tag
 * that does not describe a release with its evidence) and `stable_unreadable` (could not be read; retry). Nothing is
 * installed on any of them, and the background check never falls back to alpha.
 */
import { spawnSync } from './spawn.ts';
import { gitChildEnv } from './git-env.ts';
import { isNewerVersion, isValidVersionString } from './semver.ts';
import type { Action } from './agent-output.ts';
import { MATRIX_REQUIRED_FROM, channelSwitchCommand, type ChannelResolution, type StableLookupError } from './self-upgrade.ts';

const REPO_SLUG = 'garrytan/gbrain';
const GBRAIN_GIT_URL = `https://github.com/${REPO_SLUG}`;
export const STABLE_RECORD_BRANCH = 'stable-record';
export const STABLE_RECORD_FILE = 'stable.json';
export const STABLE_RECORD_URL = `https://raw.githubusercontent.com/${REPO_SLUG}/${STABLE_RECORD_BRANCH}/${STABLE_RECORD_FILE}`;
export const RECORD_MAX_BYTES = 64 * 1024;
const STABLE_ERRORS_DOCS = 'docs/guides/upgrades-auto-update.md#stable-channel-errors';
const SHA_RE = /^[0-9a-f]{40}$/;
const RUN_URL_RE = /^https:\/\/github\.com\/garrytan\/gbrain\/actions\/runs\/\d+(\/attempts\/\d+)?\/?$/;

export type StableCode = StableLookupError['code'];
export type StableFailure = { ok: false; code: StableCode; cause: string };

export interface StableRecord {
  schema: 1;
  version: string;
  commit: string;
  tree: string;
  soak_run: string;
  matrix_run: string | null;
  promoted_at: string;
  previous: string | null;
  rollback: boolean;
  known_bad: string[];
}

export type GitRunner = (args: string[]) => { status: number | null; stdout: string };
const runGit: GitRunner = (args) => {
  const r = spawnSync('git', args, { encoding: 'utf-8', env: gitChildEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: 15_000 });
  return { status: r.error ? null : r.status, stdout: r.stdout ?? '' };
};

/** `--channel <name>` / `--channel=<name>`: the raw value, '' when the flag has none, null when absent. */
export function parseChannelArg(args: readonly string[]): string | null {
  const at = args.findIndex(a => a === '--channel' || a.startsWith('--channel='));
  if (at === -1) return null;
  if (args[at]!.includes('=')) return args[at]!.slice('--channel='.length);
  const next = args[at + 1];
  return next && !next.startsWith('-') ? next : '';
}

/** Bounded, single-line, credential-free text safe to print and to cache. */
export function sanitizeCause(text: string): string {
  return text
    .replace(/[\s\u0000-\u001f\u007f]+/g, ' ')
    .replace(/(\w+:\/\/)[^\s/@]+@/g, '$1')
    .replace(/\b(gh[pousr]_[A-Za-z0-9]{8,}|github_pat_[A-Za-z0-9_]{8,})\b/g, '[redacted]')
    .trim()
    .slice(0, 200);
}

/** The evidence keys a record for `version` must carry: soak always; the matrix run from `matrixFrom` on. */
export function requiredEvidenceKeys(version: string, matrixFrom: string | null = MATRIX_REQUIRED_FROM): Array<'soak_run' | 'matrix_run'> {
  return matrixFrom && !isNewerVersion(version, matrixFrom) ? ['soak_run', 'matrix_run'] : ['soak_run'];
}

/** Strict parse of the evidence record; the cause names the first thing wrong. */
export function parseStableRecord(body: string, matrixFrom: string | null = MATRIX_REQUIRED_FROM): { ok: true; record: StableRecord } | { ok: false; cause: string } {
  if (body.length > RECORD_MAX_BYTES) return { ok: false, cause: `the record is larger than ${RECORD_MAX_BYTES} bytes` };
  let raw: Record<string, unknown>;
  try {
    raw = JSON.parse(body);
  } catch {
    return { ok: false, cause: 'the record is not JSON' };
  }
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, cause: 'the record is not a JSON object' };
  if (raw.schema !== 1) return { ok: false, cause: `unsupported record schema ${JSON.stringify(raw.schema ?? null)}` };
  const version = raw.version;
  if (typeof version !== 'string' || !isValidVersionString(version)) return { ok: false, cause: 'the record has no valid version' };
  for (const key of ['commit', 'tree'] as const) {
    if (typeof raw[key] !== 'string' || !SHA_RE.test(raw[key] as string)) return { ok: false, cause: `the record has no valid ${key}` };
  }
  for (const key of requiredEvidenceKeys(version, matrixFrom)) {
    if (typeof raw[key] !== 'string' || !RUN_URL_RE.test(raw[key] as string)) {
      return { ok: false, cause: `the record for ${version} lacks the evidence key ${key} (a run of ${REPO_SLUG})` };
    }
  }
  const knownBad = raw.known_bad ?? [];
  if (!Array.isArray(knownBad) || knownBad.some(v => typeof v !== 'string' || !isValidVersionString(v))) {
    return { ok: false, cause: 'known_bad is not a list of versions' };
  }
  if (knownBad.includes(version)) return { ok: false, cause: `the record lists its own version ${version} as known_bad` };
  return {
    ok: true,
    record: {
      schema: 1,
      version,
      commit: raw.commit as string,
      tree: raw.tree as string,
      soak_run: raw.soak_run as string,
      matrix_run: typeof raw.matrix_run === 'string' ? raw.matrix_run : null,
      promoted_at: typeof raw.promoted_at === 'string' ? raw.promoted_at : '',
      previous: typeof raw.previous === 'string' ? raw.previous : null,
      rollback: raw.rollback === true,
      known_bad: knownBad as string[],
    },
  };
}

/** Fetch and validate the evidence record. 5 s timeout; 404 is stable_missing, any other failure to read is unreadable. */
export async function fetchStableRecord(fetchImpl: typeof fetch = fetch, userAgent = 'gbrain'): Promise<{ ok: true; record: StableRecord } | StableFailure> {
  let res: Response;
  try {
    res = await fetchImpl(STABLE_RECORD_URL, { headers: { 'User-Agent': userAgent }, signal: AbortSignal.timeout(5_000) });
  } catch (e) {
    return { ok: false, code: 'stable_unreadable', cause: sanitizeCause(`fetching the stable record failed: ${e instanceof Error ? e.message : String(e)}`) };
  }
  if (res.status === 404) return { ok: false, code: 'stable_missing', cause: 'no stable record is published (nothing has been promoted to stable)' };
  if (!res.ok) return { ok: false, code: 'stable_unreadable', cause: `the stable record answered HTTP ${res.status}` };
  let body: string;
  try {
    body = await res.text();
  } catch (e) {
    return { ok: false, code: 'stable_unreadable', cause: sanitizeCause(`reading the stable record failed: ${e instanceof Error ? e.message : String(e)}`) };
  }
  const parsed = parseStableRecord(body);
  return parsed.ok ? parsed : { ok: false, code: 'stable_invalid', cause: sanitizeCause(parsed.cause) };
}

/**
 * The release an explicit stable upgrade installs: the record, checked against the repository's tags. The `stable`
 * tag must peel to the record's commit (a mismatch right after a promotion is the raw cache catching up: unreadable,
 * retry) and `v<version>` must be that commit (otherwise the record names no published release: invalid).
 */
export async function resolveStableRelease(deps: { git?: GitRunner; fetch?: typeof fetch } = {}): Promise<{ ok: true; version: string; commit: string; record: StableRecord } | StableFailure> {
  const { status, stdout } = (deps.git ?? runGit)(['ls-remote', '--tags', GBRAIN_GIT_URL]);
  if (status !== 0) return { ok: false, code: 'stable_unreadable', cause: `git ls-remote --tags ${GBRAIN_GIT_URL} failed (offline, or no git)` };
  const refs = new Map<string, string>();
  for (const line of stdout.split('\n')) {
    const [sha, ref] = line.trim().split('\t');
    if (sha && ref) refs.set(ref, sha);
  }
  const peel = (tag: string) => refs.get(`refs/tags/${tag}^{}`) ?? refs.get(`refs/tags/${tag}`);
  const stableCommit = peel('stable');
  const fetched = await fetchStableRecord(deps.fetch ?? fetch);
  if (!stableCommit) {
    return fetched.ok || fetched.code !== 'stable_unreadable'
      ? { ok: false, code: 'stable_missing', cause: 'the repository has no stable tag (nothing has been promoted to stable)' }
      : fetched;
  }
  if (!fetched.ok) {
    return fetched.code === 'stable_missing'
      ? { ok: false, code: 'stable_invalid', cause: 'the stable tag exists but has no published evidence record' }
      : fetched;
  }
  const { record } = fetched;
  if (stableCommit !== record.commit) {
    return { ok: false, code: 'stable_unreadable', cause: `the stable tag (${stableCommit.slice(0, 12)}) and the evidence record (${record.commit.slice(0, 12)}) disagree; a promotion may still be propagating` };
  }
  if (peel(`v${record.version}`) !== record.commit) {
    return { ok: false, code: 'stable_invalid', cause: `the record names ${record.version}, but v${record.version} is not the stable commit` };
  }
  return { ok: true, version: record.version, commit: record.commit, record };
}

/** What happened, one sentence. */
export function stableFailureMessage(f: { code: StableCode; cause: string }): string {
  const what = f.code === 'stable_missing' ? 'No release has been promoted to the stable channel yet'
    : f.code === 'stable_invalid' ? 'The stable channel has no usable release: its evidence record does not describe a promoted release'
    : 'The stable channel could not be read';
  return `${what}: ${f.cause}.`;
}

/**
 * The next step, rendered against the precedence that chose stable: retry for unreadable; otherwise wait for a
 * promotion or move this install to alpha with the command that overrides what chose stable.
 */
export function stableFailureFix(f: { code: StableCode }, res: ChannelResolution): string {
  if (f.code === 'stable_unreadable') return 'Nothing was changed. Retry in a few minutes: gbrain self-upgrade --check-only';
  return `Nothing was changed. Wait for a stable promotion, or follow every release on alpha: ${channelSwitchCommand('alpha', res)}`;
}

/**
 * The structured next step for a stable failure (agent operator contract): a read-only retry for unreadable; for
 * missing or invalid, switching to alpha is the user's choice (ask_user), with argv only when a config write is what
 * decides the channel (an env or flag override is changed where it is set).
 */
export function stableFailureAction(f: { code: StableCode }, res: ChannelResolution): Action {
  const verify = { argv: ['gbrain', 'self-upgrade', '--check-only', '--json'] };
  if (f.code === 'stable_unreadable') {
    return { argv: verify.argv, consent: [], actor: 'agent', why: 'Read-only: looks up the stable channel again and reports the channel, its source and any error code.', requires_exclusive: false, verify, docs: STABLE_ERRORS_DOCS };
  }
  const userMessage = `Stable has no usable release right now (${f.code}). Wait for a promotion, or follow every release on alpha: ${channelSwitchCommand('alpha', res)}`;
  const common = { ask_user: true as const, consent: [], why: 'Changes which releases this install follows; the user decides.', user_message: userMessage, requires_exclusive: false, verify, docs: STABLE_ERRORS_DOCS };
  return res.source === 'config' || res.source === 'default'
    ? { ...common, argv: ['gbrain', 'config', 'set', 'self_upgrade.channel', 'alpha'], actor: 'agent' }
    : { ...common, actor: 'user' };
}