Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.4 KB
Raw Blame
/**
 * #6712 PR 4b (design v3.2 §3.7): the pass row as the former cursor readers see it. A non-company source has no cursor
 * once its first pass ran, so doctor, the movement reader, the backlog, the blocked-run reader and `sources status`
 * read its pass row instead, through `passHealth`, the one rule `sync-pass-row.ts` keeps. Company sources and legacy
 * cursors keep their cursor arm in each reader.
 *
 * `nothing_pending` needs the checkout's HEAD: it is read with a hardened `rev-parse` of the source's checkout on this
 * host. A host with no checkout of the source (or one Git cannot read) gets `head: null`, and the reading then trusts
 * the converged target the pass recorded, as a cursor reader trusts a missing cursor.
 */
import { resolve } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { hardenedGitSync } from '../hardened-git.ts';
import { managedSyncResumeArgs } from '../sync-reconcile.ts';
import { hostIdFor } from './identity.ts';
import { passHealth, readLivePassRows, type PassHealth, type PassRow } from './sync-pass-row.ts';

export interface PassReading { source_id: string; row: PassRow; head: string | null; health: PassHealth }

/** HEAD of each source's checkout on this host, or null when this host has none or Git cannot read it. */
export async function readCheckoutHeads(engine: Pick<BrainEngine, 'executeRaw'>, sourceIds: readonly string[]): Promise<Map<string, string | null>> {
  const heads = new Map<string, string | null>(sourceIds.map(id => [id, null]));
  if (!sourceIds.length) return heads;
  const rows = await engine.executeRaw<{ source_id: string; local_path: string; relative_path: string }>(`SELECT b.source_id, h.local_path, b.relative_path
    FROM persistence_source_bindings b JOIN persistence_host_bindings h ON h.worktree_id=b.worktree_id AND h.host_id=$2::uuid
    WHERE b.source_id=ANY($1::text[])`, [[...sourceIds], hostIdFor(engine)]);
  for (const row of rows) {
    const out = hardenedGitSync(resolve(row.local_path, row.relative_path), ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], { timeoutMs: 10_000, maxBytes: 4096 });
    heads.set(row.source_id, out.ok ? out.stdout.toString('utf8').trim() || null : null);
  }
  return heads;
}

/**
 * The pass rows of the sources' live incarnations with their health. `stalledMs`: an open pass whose row has not moved
 * for that long reads `open_stalled` (Infinity: never). `head: false` skips the HEAD read (no `nothing_pending` test).
 */
export async function readPassReadings(engine: Pick<BrainEngine, 'executeRaw'>, opts: { sourceIds?: readonly string[]; now?: number; stalledMs?: number; head?: boolean } = {}): Promise<PassReading[]> {
  const rows = await readLivePassRows(engine, opts.sourceIds);
  if (!rows.size) return [];
  const heads = opts.head === false ? new Map<string, string | null>() : await readCheckoutHeads(engine, [...rows.keys()]);
  return [...rows].sort(([a], [b]) => a.localeCompare(b)).map(([sourceId, row]) => {
    const head = heads.get(sourceId) ?? null;
    return { source_id: sourceId, row, head, health: passHealth(row, { head, now: opts.now, stalledMs: opts.stalledMs ?? Infinity }) };
  });
}

/** A reason `passHealth` gives for a pass that keeps stopping (an open pass that stalled is the movement reader's call). */
export const passStuck = (health: PassHealth): boolean => health.reason === 'blocked' || health.reason === 'not_converged' || health.reason === 'settle_mismatch';

/** When the source started reading stuck: the pass row's `stuck_since`, else the newest pass's ending, else the row's last write. */
export function passStuckSince(row: PassRow): string {
  return row.value.obligations.stuck_since ?? row.value.telemetry.ended_at ?? row.updated_at;
}

/** The stop the newest pass names: its stop reason, else the health reason. */
export function passStopCode(reading: Pick<PassReading, 'row' | 'health'>): string {
  return reading.row.value.telemetry.stop_reason ?? reading.health.reason ?? reading.row.value.telemetry.outcome;
}

/** The plain sync that continues the source, carrying the open episode's inherited opt-outs (design §6). */
export function passResumeArgs(sourceId: string, row: PassRow): string[] {
  const inherited = row.value.obligations.episode?.inherited;
  return managedSyncResumeArgs({ sourceId, processingOptions: inherited ? { noEmbed: inherited.noEmbed, noExtract: inherited.noExtract, noSchemaPack: inherited.noSchemaPack } : null });
}