Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.3 KB
Raw Blame
/**
 * Kill switches for write-path behaviors, read from one per-process snapshot.
 *
 * Every switch is on by default unless its entry says `defaultOn: false`. An
 * environment variable overrides the brain config key; `0` or `false` (either
 * source) turns a switch off, `1` or `true` turns it on. The snapshot
 * reads every switch key in one statement and is reused for SWITCH_TTL_MS, so
 * `gbrain config set <key> false` reaches a running `serve` within that time
 * without a round trip per write. Config writes are trusted-local only (no
 * remote operation writes config), so a remote caller cannot flip a switch.
 */
import type { SqlEngine } from './model.ts';
import { DEFAULT_PREPARATION_POLICY, PREPARATION_BUDGET_CONFIG_KEYS, resolvePreparationPolicy, type PreparationPolicy } from './preparation-budget.ts';

export const WRITE_SWITCHES = {
  /** Phase 4.1/4.3/4.4: single page writes publish as a group of one, the own admission claims directly, publication reuses a warm connection. */
  single_write_group: { key: 'persistence.single_write_group', env: 'GBRAIN_SINGLE_WRITE_GROUP' },
  /** Phase 4.2: per-process cache of pre-admission reads that admission rechecks under lock. */
  preadmit_cache: { key: 'persistence.preadmit_cache', env: 'GBRAIN_PREADMIT_CACHE' },
  /** Batched waiver runs; `GBRAIN_SYNC_WAIVE_NOOP=0` wins over it. */
  waive_batch: { key: 'sync.waive_batch', env: 'GBRAIN_SYNC_WAIVE_BATCH' },
  /** Phase 4.5: a foreground write goes ahead of queued sync groups that do not name its page; off restores the FIFO and the sync side's pauses. */
  foreground_priority: { key: 'sync.foreground_priority', env: 'GBRAIN_SYNC_FOREGROUND_PRIORITY' },
  /** #6278: every preparation has a deadline and a counted attempt; off restores the 30 s budget for remember/put_page/edit_page only and never counts. */
  preparation_deadlines: { key: 'persistence.preparation_deadlines', env: 'GBRAIN_PREPARATION_DEADLINES' },
  /**
   * #6317 (B1): resident processes (`sync`, `jobs`, `autopilot`, `mcp`) defer to the first live full consumer of their host
   * (consumer-election.ts) instead of starting their own. Off by default until Phase 0's preregistered reading sets it.
   */
  single_consumer: { key: 'persistence.single_consumer', env: 'GBRAIN_SINGLE_CONSUMER', defaultOn: false },
  /**
   * Convergence PR B: a page write that meets a worktree refresh is admitted `deferred` and publishes after the refresh, instead
   * of being refused `worktree_refreshing`. Off by default; turned on per brain once every routed producer polls its receipts.
   */
  refresh_barrier: { key: 'persistence.refresh_barrier', env: 'GBRAIN_REFRESH_BARRIER', defaultOn: false },
} as const;
export type WriteSwitch = keyof typeof WRITE_SWITCHES;
export type WriteSwitches = Record<WriteSwitch, boolean>;
export const WRITE_SWITCH_KEYS: readonly string[] = Object.values(WRITE_SWITCHES).map(s => s.key);
export const SWITCH_TTL_MS = 5000;

/** `sync.write_through` as the write path and onboarding read it: on unless explicitly off (#6449 shares the predicate with activation). */
export function writeThroughConfigured(value: string | null | undefined): boolean {
  return !/^(false|0|off|no)$/i.test(value ?? 'true');
}
const off = (value: string | null | undefined) => typeof value === 'string' && /^(0|false)$/i.test(value.trim());
const on = (value: string | null | undefined) => typeof value === 'string' && /^(1|true)$/i.test(value.trim());
/** One snapshot read: the switches plus the #6278 preparation budgets (preparation-budget.ts), so a claim never reads config on its own. */
export interface WriteSwitchSnapshot { switches: WriteSwitches; preparation: PreparationPolicy }
const snapshots = new WeakMap<object, { at: number; generation: number; read: Promise<WriteSwitchSnapshot> }>();
let generation = 0;
const SNAPSHOT_KEYS: readonly string[] = [...WRITE_SWITCH_KEYS, ...PREPARATION_BUDGET_CONFIG_KEYS];

function resolve(configured: Map<string, string>): WriteSwitchSnapshot {
  const out = {} as WriteSwitches;
  for (const [name, { key, env, defaultOn }] of Object.entries(WRITE_SWITCHES) as Array<[WriteSwitch, { key: string; env: string; defaultOn?: boolean }]>) {
    const fromEnv = process.env[env];
    const fromConfig = configured.get(key);
    out[name] = off(fromEnv) ? false : on(fromEnv) ? true : fromConfig === undefined ? defaultOn ?? true : !off(fromConfig);
  }
  return { switches: out, preparation: resolvePreparationPolicy(configured) };
}

/** Read-through views of an engine (preparation config, pre-admission cache) and the engine they read through. */
const views = new WeakMap<object, object>();
export function registerEngineView<T extends object>(view: T, engine: object): T { views.set(view, engine); return view; }
/** The engine a view reads through (itself when it is not a view), so a view shares its engine's snapshots and memos. */
export function viewedEngine<T extends object>(engine: T): T { return (views.get(engine) as T | undefined) ?? engine; }

/**
 * The switch snapshot of `engine`'s brain, at most SWITCH_TTL_MS old. A failed read is not kept.
 * `signal` cancels a read this call starts (the consumer's tick reads under its phase deadline).
 */
export function readWriteSwitches(viewed: SqlEngine, opts: { now?: () => number; signal?: AbortSignal } = {}): Promise<WriteSwitches> {
  return readWriteSwitchSnapshot(viewed, opts).then(snapshot => snapshot.switches);
}
/** The switches and the preparation budgets of `engine`'s brain, from the same snapshot. */
export function readWriteSwitchSnapshot(viewed: SqlEngine, opts: { now?: () => number; signal?: AbortSignal } = {}): Promise<WriteSwitchSnapshot> {
  const now = opts.now ?? Date.now;
  const engine = viewedEngine(viewed);
  const held = snapshots.get(engine);
  if (held && held.generation === generation && now() - held.at < SWITCH_TTL_MS) return held.read;
  const read = engine.executeRaw<{ key: string; value: string }>('SELECT key,value FROM config WHERE key = ANY($1::text[])', [SNAPSHOT_KEYS], { signal: opts.signal })
    .then(rows => resolve(new Map(rows.map(row => [row.key, row.value]))));
  snapshots.set(engine, { at: now(), generation, read });
  read.catch(() => { if (snapshots.get(engine)?.read === read) snapshots.delete(engine); });
  return read;
}
/**
 * GBRA-156: a whole-table config read this process just took (the CLI's connect-time merge) is the switch snapshot as of
 * that read, kept for SWITCH_TTL_MS like any other; a snapshot already held is left alone.
 */
export function seedWriteSwitchSnapshot(viewed: object, rows: Record<string, string>, now: number = Date.now()): void {
  const engine = viewedEngine(viewed);
  const held = snapshots.get(engine);
  if (held && held.generation === generation && now - held.at < SWITCH_TTL_MS) return;
  snapshots.set(engine, { at: now, generation, read: Promise.resolve(resolve(new Map(Object.entries(rows)))) });
}
/** The preparation budgets in effect (defaults when the read fails). */
export async function readPreparationPolicy(engine: SqlEngine): Promise<PreparationPolicy> {
  return readWriteSwitchSnapshot(engine).then(snapshot => snapshot.preparation, () => ({ ...DEFAULT_PREPARATION_POLICY }));
}

export async function writeSwitchOn(engine: SqlEngine, name: WriteSwitch): Promise<boolean> {
  return (await readWriteSwitches(engine))[name];
}

/** Test seam: the next read of every engine sees the current config. */
export function resetWriteSwitches(): void { generation++; }