Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.6 KB
Raw Blame
/**
 * #6743: shared-skills cleanup convergence for `gbrain bootstrap harness`.
 *
 * A rotation leaves each old shared-skills enrollment with that enrollment's
 * own credential, then revokes the credential (leave before revoke:
 * `leave_brain` is principal-owned, so a revoked token can never leave). Two
 * rules keep a re-run converging:
 *
 * - An enrollment whose credential is already revoked is inert remotely: its
 *   leave still runs locally (adapter receipt deactivation, native-router
 *   removal, owned-file cleanup that keeps edited files) and the entry is
 *   recorded as left with reason `credential_revoked`.
 * - Each carried token id is revoked and cleared on its own. Only an id that a
 *   not-yet-left enrollment still holds stays on the receipt.
 *
 * Whatever is still pending is reported per id: the apply exits
 * `bootstrap_cleanup_pending` (14) instead of 0, with a fix that re-runs the
 * command when every id can converge and names the owner's step when one
 * cannot. `--status` and doctor read the same items.
 */
import { existsSync, rmSync } from 'node:fs';
import { join } from 'node:path';
import { cliRenderContext, renderAction, type Action, type RenderedAction } from '../agent-output.ts';
import { loadConfig, toEngineConfig } from '../config.ts';
import type { BrainEngine } from '../engine.ts';
import { createEngine } from '../engine-factory.ts';
import { TOKEN_ID_RE } from '../token-mint.ts';
import type { HarnessReceipt } from './format.ts';
import { probeLivePgliteHolder } from './uninstall.ts';
import type { resolveHarnessDeps } from './harness.ts';

type SkillsEntry = NonNullable<HarnessReceipt['shared_skills']>[number];
type Deps = ReturnType<typeof resolveHarnessDeps>;

export type TokenState = 'active' | 'revoked' | 'missing' | 'unknown';
export type TokenStateLookup = (ids: string[]) => Promise<Record<string, TokenState>>;

export const BOOTSTRAP_CLEANUP_PENDING = 'bootstrap_cleanup_pending';
export const HARNESS_CLEANUP_DOCS = 'docs/guides/bootstrap.md#cleanup-pending';

export interface CleanupItem {
  /** The carried token id; null for an enrollment that used a supplied credential. */
  token_id: string | null;
  host: string | null;
  token: TokenState;
  state: 'revoke_pending' | 'leave_pending' | 'enrollment_retained' | 'credential_unreadable';
  /** True when a plain re-run of the bootstrap command can finish this id. */
  converges: boolean;
  /** The owner's step when a re-run cannot finish it. */
  user_message?: string;
}

/** Read-only: each id's row state in access_tokens. */
export async function tokenStatesWith(engine: Pick<BrainEngine, 'executeRaw'>, ids: string[]): Promise<Record<string, TokenState>> {
  const valid = ids.filter(id => TOKEN_ID_RE.test(id));
  const rows = valid.length === 0 ? [] : await engine.executeRaw<{ id: string; revoked: boolean }>(
    'SELECT id::text AS id, revoked_at IS NOT NULL AS revoked FROM access_tokens WHERE id::text = ANY($1::text[])', [valid]);
  return Object.fromEntries(ids.map(id => {
    const row = rows.find(r => r.id.toLowerCase() === id.toLowerCase());
    return [id, !row ? 'missing' : row.revoked ? 'revoked' : 'active'];
  }));
}

export async function defaultTokenStates(ids: string[]): Promise<Record<string, TokenState>> {
  const cfg = loadConfig();
  if (!cfg) throw new Error('no brain configured');
  // A live serve holds the PGLite single-writer lock (the normal state for --status): the states read unknown.
  if (cfg.database_path && probeLivePgliteHolder(cfg.database_path) !== null) throw new Error('a live gbrain serve holds this PGLite brain');
  const engineConfig = toEngineConfig(cfg);
  const engine = await createEngine(engineConfig);
  await engine.connect(engineConfig);
  try {
    return await tokenStatesWith(engine, ids);
  } finally {
    await engine.disconnect();
  }
}

/** A lookup that cannot reach the brain reads every id as unknown, never as revoked. */
async function lookupStates(lookup: TokenStateLookup, ids: string[]): Promise<Record<string, TokenState>> {
  if (ids.length === 0) return {};
  const states = await lookup(ids).catch(() => ({} as Record<string, TokenState>));
  return Object.fromEntries(ids.map(id => [id, states[id] ?? 'unknown']));
}

export async function credentialRevoked(entry: SkillsEntry, d: Pick<Deps, 'tokenStates'>): Promise<boolean> {
  if (!entry.token_id) return false;
  return (await lookupStates(d.tokenStates, [entry.token_id]))[entry.token_id] === 'revoked';
}

/**
 * Leave an enrollment whose credential is already revoked. The local leave
 * runs with a caller that never contacts the host (a revoked bearer cannot
 * authenticate `leave_brain`), and the remote membership counts as inert.
 */
export async function leaveRevokedEnrollment(entry: SkillsEntry, d: Pick<Deps, 'installSharedSkills' | 'log' | 'logError'>): Promise<boolean> {
  const result = await d.installSharedSkills(
    { version: 1, mcp_url: entry.url, issuer_url: entry.url.replace(/\/mcp$/, ''), client_id: entry.token_id ?? `revoked-${entry.host}` },
    { harness: entry.host, root: entry.root, name: entry.name, remove: true,
      toolCaller: async () => { throw new Error('credential_revoked: the cleanup credential is revoked'); } },
  ).catch(() => ({ status: 'pending', retained_files: undefined }));
  if (result.status !== 'left' && result.status !== 'left_with_retained_files') {
    entry.status = 'pending';
    entry.reason = 'cleanup_unavailable';
    d.logError(`shared skills (${entry.host}): local cleanup of the enrollment for revoked token ${entry.token_id} did not finish; a re-run retries it.`);
    return false;
  }
  entry.status = result.status;
  entry.reason = 'credential_revoked';
  entry.retained_files = result.retained_files;
  rmSync(join(entry.root, 'credentials.json'), { force: true });
  d.log(`shared skills (${entry.host}): token ${entry.token_id} is already revoked, so its enrollment cannot leave remotely and is inert; ` +
    `local cleanup finished${result.retained_files?.length ? ` (edited files retained: ${result.retained_files.join(', ')})` : ''}.`);
  return true;
}

const isCurrentEntry = (receipt: HarnessReceipt, entry: SkillsEntry) =>
  entry.token_id === undefined || entry.token_id === receipt.harness_tokens?.[entry.host]?.id;

/** Not-yet-left enrollments other than this run's current ones (without a run: the receipt's harness tokens). */
function staleEntries(receipt: HarnessReceipt, current?: ReadonlySet<SkillsEntry>): SkillsEntry[] {
  return (receipt.shared_skills ?? []).filter(entry => !entry.status.startsWith('left') &&
    !(current ? current.has(entry) : isCurrentEntry(receipt, entry)));
}

const heldIds = (receipt: HarnessReceipt) =>
  new Set((receipt.shared_skills ?? []).filter(e => !e.status.startsWith('left')).flatMap(e => e.token_id ? [e.token_id] : []));

function idsToClassify(receipt: HarnessReceipt, current?: ReadonlySet<SkillsEntry>): string[] {
  return [...new Set([...(receipt.token.previous_ids ?? []), ...staleEntries(receipt, current).flatMap(e => e.token_id ? [e.token_id] : [])])];
}

/** The pending cleanup, one item per stale enrollment and per carried id no enrollment holds. */
export function harnessCleanupItems(receipt: HarnessReceipt, states: Record<string, TokenState>, current?: ReadonlySet<SkillsEntry>): CleanupItem[] {
  const items: CleanupItem[] = staleEntries(receipt, current).map(entry => {
    const token = entry.token_id ? states[entry.token_id] ?? 'unknown' : 'unknown';
    const base = { token_id: entry.token_id ?? null, host: entry.host, token };
    const id = entry.token_id ?? '(supplied)';
    if (entry.reason === 'cleanup_unavailable' && token !== 'revoked') {
      return { ...base, state: 'credential_unreadable', converges: false,
        user_message: `The cleanup credential of the old ${entry.host} enrollment (${join(entry.root, 'credentials.json')}) is unreadable, so it cannot leave. ` +
          `Restore that file, or revoke token ${id} by id (\`gbrain auth revoke\`): an enrollment whose credential is revoked counts as inert ` +
          'and the next re-run finishes its local cleanup.' };
    }
    if (entry.reason === 'remote_membership_pending' || entry.reason === 'cleanup_unavailable') {
      if (token !== 'missing') return { ...base, state: 'leave_pending', converges: true };
      return { ...base, state: 'leave_pending', converges: false,
        user_message: `Token ${id} is not in this brain's token table, so its ${entry.host} enrollment cannot leave. ` +
          'Check that this machine\'s brain config names the brain the harness serves (`gbrain auth list` shows its tokens).' };
    }
    return { ...base, state: 'enrollment_retained', converges: false,
      user_message: `The old ${entry.host} enrollment (token ${id}) is kept working because the current shared-skills enrollment is not ready ` +
        '(`gbrain bootstrap harness --status` shows why). Resolve that; the next re-run leaves the old enrollment, then revokes its token.' };
  });
  const held = heldIds(receipt);
  for (const id of receipt.token.previous_ids ?? []) {
    if (!held.has(id)) items.push({ token_id: id, host: null, token: states[id] ?? 'unknown', state: 'revoke_pending', converges: true });
  }
  return items;
}

/** Read-only report for `--status` and doctor. */
export async function harnessCleanupReport(receipt: HarnessReceipt, lookup: TokenStateLookup): Promise<CleanupItem[]> {
  return harnessCleanupItems(receipt, await lookupStates(lookup, idsToClassify(receipt)));
}

/**
 * Apply step 10: leave stale enrollments, then revoke each carried id that no
 * remaining enrollment holds. Returns what is still pending.
 */
export async function convergeHarnessCleanup(o: {
  receipt: HarnessReceipt;
  prior: HarnessReceipt | null | undefined;
  current: ReadonlySet<SkillsEntry>;
  wired: boolean;
  skillsReady: boolean;
  memoryOnly: boolean;
  leave: (entry: SkillsEntry, d: Deps) => Promise<boolean>;
  save: () => void;
}, d: Deps): Promise<CleanupItem[]> {
  const { receipt } = o;
  const states = await lookupStates(d.tokenStates, idsToClassify(receipt, o.current));
  const cached: Deps = { ...d, tokenStates: async ids => Object.fromEntries(ids.map(id => [id, states[id] ?? 'unknown'])) };
  // A working prior enrollment stays until the current one is ready (the follow-approval boundary);
  // one whose credential is revoked is already dead, so it always leaves.
  const priorEnrollment = (o.prior?.shared_skills ?? []).some(entry => !entry.status.startsWith('left') &&
    existsSync(join(entry.root, 'shared-skills', 'receipt.json')));
  const leaveAll = (o.wired && (o.skillsReady || !priorEnrollment)) || o.memoryOnly;
  for (const entry of staleEntries(receipt, o.current)) {
    if (!leaveAll && states[entry.token_id ?? ''] !== 'revoked') continue;
    await o.leave(entry, cached);
    o.save();
  }
  receipt.shared_skills = receipt.shared_skills?.filter(entry => entry.status !== 'left');
  o.save();
  if (o.wired && receipt.token.previous_ids?.length) {
    const held = heldIds(receipt);
    const remaining: string[] = [];
    for (const id of receipt.token.previous_ids) {
      if (held.has(id)) { remaining.push(id); continue; }
      try {
        const revoked = await d.revokeById(id);
        d.log(revoked ? `previous harness token revoked (id ${id}).` : `previous harness token was already revoked (id ${id}).`);
      } catch (e) {
        remaining.push(id);
        d.logError(`could not revoke a previous harness token (${e instanceof Error ? e.message : String(e)}); kept on the receipt (id ${id}) for the next re-run.`);
      }
    }
    if (remaining.length > 0) receipt.token.previous_ids = remaining;
    else delete receipt.token.previous_ids;
    o.save();
  }
  const items = harnessCleanupItems(receipt, states, o.current);
  if (items.length > 0) d.logError(`cleanup pending (${BOOTSTRAP_CLEANUP_PENDING}):\n${cleanupLines(items).join('\n')}`);
  return items;
}

const TOKEN_WORDS: Record<TokenState, string> = {
  active: 'active', revoked: 'revoked', missing: "not in this brain's token table", unknown: 'status unknown',
};

function describeItem(item: CleanupItem): string {
  const who = item.token_id ?? `${item.host} (supplied credential)`;
  const what = item.state === 'revoke_pending'
    ? item.token === 'revoked' ? 'no enrollment holds it; a re-run clears it from the receipt' : 'no enrollment holds it; a re-run revokes it (or `gbrain auth revoke` by id)'
    : item.state === 'leave_pending'
      ? item.token === 'revoked' ? 'enrollment cleanup pending; a re-run finishes it locally' : 'enrollment leave pending'
      : item.state === 'credential_unreadable' ? 'its cleanup credential is unreadable' : 'kept for the previous enrollment until the current one is ready';
  return `${who}: ${TOKEN_WORDS[item.token]}; ${what}`;
}

export function cleanupLines(items: CleanupItem[]): string[] {
  return items.map(item => `  pending: ${describeItem(item)}${item.user_message ? ` — ${item.user_message}` : ''}`);
}

/** Doctor's wording: per id, a revoked credential awaiting cleanup reads apart from an active one. */
export function cleanupDoctorMessage(items: CleanupItem[]): string {
  return `shared-skills cleanup pending for ${items.length} previous harness credential(s): ${items.map(describeItem).join('; ')}. ` +
    'Leave before revoke: re-run `gbrain bootstrap harness`, which leaves each old enrollment and then revokes its token. ' +
    'Revoke a token by hand only after its enrollment has left, or when its cleanup credential is lost.';
}

/** The apply's re-run argv: this run's flags, the token value masked, `--yes` added. */
function rerunArgv(raw: readonly string[]): { argv: string[]; token: boolean } {
  const argv = ['gbrain', 'bootstrap', 'harness'];
  let token = false;
  for (let i = 0; i < raw.length; i++) {
    if (raw[i] === '--json') continue;
    if (raw[i] === '--token') { i++; token = true; argv.push('--token', '<TOKEN>'); continue; }
    argv.push(raw[i]!);
  }
  if (!argv.includes('--yes')) argv.push('--yes');
  return { argv, token };
}

export function harnessCleanupFix(items: CleanupItem[], raw: readonly string[]): Action {
  const rerun = rerunArgv(raw);
  const verify = { argv: ['gbrain', 'bootstrap', 'harness', '--status', '--json'] };
  const inputs = rerun.token ? [{ name: 'TOKEN', how: 'The same token this run was given with --token.' }] : undefined;
  const blocked = items.filter(item => !item.converges);
  if (blocked.length === 0) {
    return { argv: rerun.argv, ...(inputs ? { inputs } : {}), consent: [], actor: 'agent', verify, docs: HARNESS_CLEANUP_DOCS, requires_exclusive: false,
      why: 'The same approved command leaves each old shared-skills enrollment, then revokes its token; a leave that was offline is retried.' };
  }
  const first = blocked[0]!;
  const revokeStep = first.state === 'credential_unreadable' && first.token_id !== null;
  return {
    argv: revokeStep ? ['gbrain', 'auth', 'revoke', '--id', first.token_id!] : rerun.argv,
    ...(!revokeStep && inputs ? { inputs } : {}),
    consent: [], actor: 'user', verify, docs: HARNESS_CLEANUP_DOCS, requires_exclusive: false,
    why: 'A re-run alone cannot finish this cleanup; the owner of the old credential acts first.',
    user_message: `${blocked.map(item => item.user_message).join(' ')} Then re-run: ${rerun.argv.join(' ')}`,
  };
}

/** The apply/status `--json` fields: per-id items always; status, code and fix only when the run otherwise succeeded. */
export function cleanupOutcomeFields(items: CleanupItem[], ok: boolean, raw: readonly string[] | null):
  { cleanup?: CleanupItem[]; status?: string; code?: string; fix?: RenderedAction } {
  if (items.length === 0) return {};
  if (!ok) return { cleanup: items };
  return { status: 'cleanup_pending', code: BOOTSTRAP_CLEANUP_PENDING, cleanup: items,
    ...(raw ? { fix: renderAction(harnessCleanupFix(items, raw), cliRenderContext()) } : {}) };
}