Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.6 KB
Raw Blame
/**
 * A set of cycle leases held as one (#6242).
 *
 * A source-scoped cycle that also runs brain-wide phases holds its source
 * lease (`gbrain-cycle:<source>`) and, when it can get it, the shared
 * maintenance lease (`gbrain-cycle`). `acquireLeaseSet` takes the required
 * ids, then the optional ones, without waiting, in that fixed order with
 * duplicates dropped. A busy required lease or any acquire that throws
 * releases everything taken so far, so a failed attempt never strands a row;
 * a busy optional lease is reported and the set holds what it has. The
 * combined handle refreshes every lease in order and reports false at the
 * first one it no longer owns (a fenced refresh), and releases every lease
 * even when one release throws, rethrowing the first failure.
 *
 * When the maintenance lease is busy the cycle runs its source phases and
 * reports each brain-wide phase with `maintenanceLockBusySkip`.
 */
import type { Action } from '../agent-output.ts';
import type { CyclePhase, PhaseResult } from '../cycle.ts';
import type { LockSnapshot } from '../db-lock.ts';
import { PHASE_SCOPE } from './phase-scope.ts';

export const MAINTENANCE_LEASE_ID = 'gbrain-cycle';
export const MAINTENANCE_LOCK_BUSY = 'maintenance_lock_busy';

export interface Lease {
  refresh: () => Promise<boolean>;
  release: () => Promise<void>;
}

export type LeaseSetResult =
  | { status: 'acquired'; lease: Lease; busyOptional: string | null }
  | { status: 'busy'; busyId: string };

/** Combine held leases into one: refresh in order (false on first loss), release in reverse, every one. */
export function combineLeases(leases: readonly Lease[]): Lease {
  return {
    refresh: async () => {
      for (const lease of leases) {
        if (!(await lease.refresh())) return false;
      }
      return true;
    },
    release: async () => {
      let first: unknown;
      let failed = false;
      for (const lease of [...leases].reverse()) {
        try {
          await lease.release();
        } catch (e) {
          if (!failed) { first = e; failed = true; }
        }
      }
      if (failed) throw first;
    },
  };
}

export async function acquireLeaseSet(
  required: readonly string[],
  acquire: (id: string) => Promise<Lease | null>,
  optional: readonly string[] = [],
): Promise<LeaseSetResult> {
  const held: Lease[] = [];
  const rollback = async () => {
    await combineLeases(held).release().catch((e: unknown) => {
      console.error(`[cycle] lease rollback release failed: ${e instanceof Error ? e.message : String(e)} — a row may remain in gbrain_cycle_locks until TTL expiry`);
    });
  };
  const take = async (id: string): Promise<Lease | null> => {
    try {
      return await acquire(id);
    } catch (e) {
      await rollback();
      throw e;
    }
  };
  const requiredIds = new Set(required);
  for (const id of requiredIds) {
    const lease = await take(id);
    if (lease === null) {
      await rollback();
      return { status: 'busy', busyId: id };
    }
    held.push(lease);
  }
  for (const id of new Set(optional)) {
    if (requiredIds.has(id)) continue;
    const lease = await take(id);
    if (lease === null) return { status: 'acquired', lease: combineLeases(held), busyOptional: id };
    held.push(lease);
  }
  return { status: 'acquired', lease: combineLeases(held), busyOptional: null };
}

/** The skipped result for a brain-wide phase whose maintenance lease another cycle holds. */
export function maintenanceLockBusySkip(phase: CyclePhase, holder: LockSnapshot | null): PhaseResult {
  const fix: Action = {
    argv: ['gbrain', 'dream', '--phase', phase],
    consent: ['paid'],
    actor: 'agent',
    why: `Runs ${phase} once ${MAINTENANCE_LEASE_ID} is free (the holder usually runs it itself); LLM-backed phases spend, so ask the user first.`,
    verify: { argv: ['gbrain', 'status', '--section', 'locks', '--json'] },
    requires_exclusive: false,
  };
  const by = holder ? ` by pid ${holder.holder_pid} on ${holder.holder_host}` : '';
  return {
    phase,
    status: 'skipped',
    duration_ms: 0,
    summary: `skipped: brain-wide maintenance lease ${MAINTENANCE_LEASE_ID} is held${by}; source phases ran`,
    details: {
      reason: MAINTENANCE_LOCK_BUSY,
      code: MAINTENANCE_LOCK_BUSY,
      phase_scope: PHASE_SCOPE[phase],
      lock_id: MAINTENANCE_LEASE_ID,
      ...(holder ? { lock_holder: { id: holder.id, holder_pid: holder.holder_pid, holder_host: holder.holder_host, age_ms: holder.age_ms } } : {}),
      why: 'Another cycle, usually autopilot maintenance, holds the brain-wide lease, so this phase would have run twice at once.',
      fix,
    },
  };
}