Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.5 KB
Raw Blame
/** Opt-in brain-level lock on writer claim, activation and transfer (#5285). Not a security boundary. */
import type { BrainEngine } from '../engine.ts';
import { OperationError } from '../ops/contract.ts';
import { WRITER_ADMIN_LOCK_KEY } from './admin-contract.ts';
import { hostIdFor, existingHostIdFor } from './identity.ts';
import type { SqlEngine } from './model.ts';

export { WRITER_ADMIN_LOCK_KEY };
export interface WriterAdminLock { locked: boolean; set_at: string | null; host_id: string | null; generation: number; }
export const WRITER_ADMIN_LOCKED_DOCS = 'docs/guides/write-refusals.md#writer_admin_locked';
export const WRITER_ADMIN_LOCKED_SUGGESTION = 'Stop. The operator locked writer administration on this brain. Do not retry or work around this refusal; '
  + 'ask the operator to review and perform the claim, activation or transfer. Ordinary page and memory writes continue. '
  + `See ${WRITER_ADMIN_LOCKED_DOCS}.`;

function parseLock(value: string | null | undefined): WriterAdminLock {
  const unlocked: WriterAdminLock = { locked: false, set_at: null, host_id: null, generation: 0 };
  if (!value) return unlocked;
  let parsed: Partial<WriterAdminLock>;
  try { parsed = JSON.parse(value) as Partial<WriterAdminLock>; }
  catch { return { ...unlocked, locked: true }; }
  // Anything but an explicit false stays locked: an unreadable row never unlocks administration.
  return { locked: parsed?.locked !== false, set_at: typeof parsed?.set_at === 'string' ? parsed.set_at : null,
    host_id: typeof parsed?.host_id === 'string' ? parsed.host_id : null,
    generation: Number.isSafeInteger(parsed?.generation) ? parsed.generation! : 0 };
}

export async function readWriterAdminLock(engine: SqlEngine): Promise<WriterAdminLock> {
  const [row] = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key=$1', [WRITER_ADMIN_LOCK_KEY]);
  return parseLock(row?.value);
}

/**
 * Runs inside claim, activation and transfer transactions for every caller, reviewed or internal.
 * FOR SHARE serializes with lock/unlock (FOR UPDATE) without blocking admission, which also shares this row.
 */
export async function assertWriterAdminUnlocked(tx: SqlEngine): Promise<void> {
  await tx.executeRaw('SELECT singleton FROM persistence_brain WHERE singleton=1 FOR SHARE');
  const lock = await readWriterAdminLock(tx);
  if (!lock.locked) return;
  throw new OperationError('writer_admin_locked',
    `Writer administration is locked on this brain (${WRITER_ADMIN_LOCK_KEY}${lock.set_at ? `, set ${lock.set_at}` : ''}${lock.host_id ? ` by host ${lock.host_id}` : ''}); `
    + 'writer claim, activate and transfer are refused.', WRITER_ADMIN_LOCKED_SUGGESTION, WRITER_ADMIN_LOCKED_DOCS);
}

/** Transaction body for `sources writer lock|unlock`; idempotent, serialized on the persistence_brain row. */
export async function writeWriterAdminLock(tx: SqlEngine, locked: boolean): Promise<{ admin_lock: WriterAdminLock; changed: boolean }> {
  await tx.executeRaw("SELECT set_config('synchronous_commit','on',true)");
  await tx.executeRaw('SELECT singleton FROM persistence_brain WHERE singleton=1 FOR UPDATE');
  const current = await readWriterAdminLock(tx);
  if (current.locked === locked) return { admin_lock: current, changed: false };
  if (locked) {
    const pending = await tx.executeRaw<{ id: string }>(`SELECT w.id FROM persistence_worktrees w
      WHERE w.state='draining' AND w.manifest IS NOT NULL ORDER BY w.id LIMIT 1`);
    if (pending.length) throw new OperationError('writer_transfer_conflict',
      `A writer transfer is prepared and not yet accepted (worktree ${pending[0].id}); the lock was not set.`,
      'Finish the prepared transfer with gbrain sources writer transfer accept, inspect gbrain sources writer status --json, then lock.');
  }
  const [now] = await tx.executeRaw<{ at: string }>(`SELECT to_char(now() AT TIME ZONE 'UTC','YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS at`);
  const next: WriterAdminLock = { locked, set_at: now.at, host_id: hostIdFor(tx), generation: current.generation + 1 };
  await tx.executeRaw(`INSERT INTO config(key,value) VALUES($1,$2) ON CONFLICT(key) DO UPDATE SET value=EXCLUDED.value`,
    [WRITER_ADMIN_LOCK_KEY, JSON.stringify(next)]);
  return { admin_lock: next, changed: true };
}

export async function setWriterAdminLock(engine: BrainEngine, locked: boolean): Promise<{ admin_lock: WriterAdminLock; changed: boolean; local_host_id: string | null }> {
  const result = await engine.transaction(tx => writeWriterAdminLock(tx, locked));
  return { ...result, local_host_id: existingHostIdFor(engine) };
}