Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.1 KB
Raw Blame
import type { BrainEngine } from '../engine.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { activatePersistence, type ActivationReport } from './activation.ts';
import { hostIdFor, existingHostIdFor } from './identity.ts';
import { acquireWorktree, getWorktreeBinding, type WorktreeBinding } from './ownership.ts';
import type { NativeLockHandle } from './native-lock.ts';
import { declarePersistenceProtocol } from './protocol.ts';
import { managedFilesystemDatastorePath, refreshManagedFilesystemRoots } from './filesystem-guard.ts';
import { assertWriterAdminState, WRITER_INSPECTION_HINT } from './admin-intent.ts';
import { assertWriterAdminUnlocked } from './admin-lock.ts';
import { notQuiescedError } from './blocking-effects.ts';
import { NOT_PAGE_EMBEDDING_LEASE } from '../page-embedding-lease.ts';

export async function activateSharedSkillPersistence(engine: BrainEngine,
  options: { confirmQuiesced?: boolean; dryRun?: boolean; expectedState?: string } = {}): Promise<{ activated: boolean; protocol_version: 2; filesystem_sources: number; drift_audit?: ActivationReport['drift_audit'] }> {
  const quiescence = () => new OperationError('writer_not_quiesced',
    'Stop and exclude older canonical writers and direct-file skill servers before enabling shared skill publication.',
    'Run this activation on every canonical owner only after verifying process shutdown and canonical-root write access.');
  if (options.confirmQuiesced !== true) throw quiescence();
  const hostId = options.dryRun || options.expectedState !== undefined ? existingHostIdFor(engine) : hostIdFor(engine);
  const loadBindings = async (tx: BrainEngine): Promise<WorktreeBinding[]> => {
    const roots = await tx.executeRaw<{ source_id: string }>(`SELECT b.source_id FROM persistence_source_bindings b
      JOIN sources s ON s.id=b.source_id AND s.incarnation=b.source_incarnation WHERE NOT s.archived ORDER BY b.worktree_id,b.source_id`);
    const bindings: WorktreeBinding[] = [];
    for (const root of roots) {
      const binding = await getWorktreeBinding(tx, root.source_id, hostId);
      if (!binding || binding.owner_host_id !== hostId || binding.state !== 'active' || !binding.local_path) throw quiescence();
      bindings.push(binding);
    }
    if (!bindings.length) {
      throw opError('writer_registration_required', 'Shared publication requires a registered canonical source root.',
        'No active source has a registered canonical owner, so shared skill publication was not enabled. Check writer status; claiming a source root is a deliberate topology change the operator reviews.',
        { fix: { argv: ['gbrain', 'sources', 'writer', 'status', '--json'], consent: [], actor: 'agent', why: 'Shows each source\'s canonical owner and claim, read-only.', requires_exclusive: false } });
    }
    return bindings;
  };
  const initial = await loadBindings(engine);
  const base = await activatePersistence(engine, { confirmQuiesced: true,
    dryRun: options.expectedState !== undefined || options.dryRun, expectedState: options.expectedState });
  if (options.expectedState !== undefined && !base.enabled) throw new OperationError('writer_registration_required',
    'Activate managed persistence first, then review fresh writer status before enabling shared skills.', WRITER_INSPECTION_HINT);
  const locks: NativeLockHandle[] = [];
  try {
    for (const binding of [...new Map(initial.map(row => [row.worktree_id, row])).values()]) {
      const lock = await acquireWorktree(binding, 0, undefined, undefined, { yieldLanes: true });
      if (!lock) throw quiescence();
      locks.push(lock);
    }
    return await engine.transaction(async tx => {
      await tx.executeRaw("SELECT set_config('synchronous_commit','on',true),set_config('lock_timeout','1s',true)");
      await assertWriterAdminState(tx, options.expectedState);
      await tx.executeRaw('SELECT singleton FROM persistence_brain WHERE singleton=1 FOR UPDATE');
      await declarePersistenceProtocol(tx);
      await assertWriterAdminUnlocked(tx);
      await tx.executeRaw('SELECT id FROM persistence_worktrees ORDER BY id FOR UPDATE');
      await tx.executeRaw('SELECT id FROM sources ORDER BY id FOR SHARE');
      await tx.executeRaw('LOCK TABLE gbrain_cycle_locks IN SHARE MODE');
      const current = await loadBindings(tx);
      const identity = (rows: WorktreeBinding[]) => JSON.stringify(rows.map(row => [row.source_id, row.source_incarnation, row.worktree_id,
        row.owner_host_id, String(row.owner_epoch), String(row.topology_generation), row.relative_path, row.local_path, row.coordination_path]));
      if (identity(current) !== identity(initial)
        || (await tx.executeRaw(`SELECT id FROM gbrain_cycle_locks WHERE ${NOT_PAGE_EMBEDDING_LEASE} LIMIT 1`)).length) throw quiescence();
      if ((await tx.executeRaw("SELECT id FROM persistence_requests WHERE state IN ('queued','deferred','running','recovering') OR recovery IS NOT NULL LIMIT 1")).length
        || (await tx.executeRaw("SELECT id FROM persistence_effects WHERE state IN ('queued','running') OR recovery IS NOT NULL LIMIT 1")).length) {
        throw await notQuiescedError(tx, quiescence().message, { queuedEffects: true });
      }
      if (options.dryRun) return { activated: false, protocol_version: 2, filesystem_sources: current.length,
        ...(base.drift_audit ? { drift_audit: base.drift_audit } : {}) };
      for (const binding of current) await tx.executeRaw(`INSERT INTO persistence_writer_protocols(worktree_id,host_id,owner_epoch,protocol_version)
        VALUES($1::uuid,$2::uuid,$3,2) ON CONFLICT(worktree_id,host_id) DO UPDATE SET
        owner_epoch=excluded.owner_epoch,protocol_version=2,registered_at=now()`, [binding.worktree_id, hostId, binding.owner_epoch]);
      await tx.executeRaw("SELECT set_config('gbrain.writer_quiesced','true',true)");
      await tx.executeRaw('UPDATE persistence_brain SET writer_protocol_floor=2,skill_bundles_enabled=true WHERE singleton=1');
      await refreshManagedFilesystemRoots(tx, managedFilesystemDatastorePath(engine));
      return { activated: true, protocol_version: 2, filesystem_sources: current.length };
    });
  } finally { for (const lock of locks.reverse()) await lock.release(); }
}