Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.8 KB
Raw Blame
/**
 * GBRA-133 PR 2a: the serve side of `sync_nudge` and the marker a trigger records. One rule for every submitter:
 * a managed source asks for freshness (its checkout's HEAD; it never pulls), a classic source asks for a pull unless
 * the caller named an intent, and a freshness marker with no head takes the checkout's HEAD now.
 */
import type { BrainEngine } from '../engine.ts';
import { SYNC_NUDGE_VERSION, type SyncNudgeRequest, type SyncNudgeResponse } from '../context/sync-ipc.ts';
import { MARKER_INTENTS, upsertMarker, type MarkerIntent, type MarkerRequester, type WantedMarker } from './store.ts';
import { revParseHead } from './detect.ts';
import { readManagedMode } from '../persistence/managed-mode.ts';
import { nudgeResidentNotifier, residentNotifier } from './resident.ts';

const SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;

/** Whether the source is a managed one (bound to a worktree on an activated brain), and its checkout root. */
export async function sourceSyncShape(engine: BrainEngine, sourceId: string): Promise<{ exists: boolean; managed: boolean; root: string | null }> {
  const [row] = await engine.executeRaw<{ local_path: string | null; root: string | null; bound: unknown }>(
    `SELECT s.local_path, h.local_path AS root, (b.source_id IS NOT NULL) AS bound
       FROM sources s
       LEFT JOIN persistence_source_bindings b ON b.source_id = s.id AND b.source_incarnation = s.incarnation
       LEFT JOIN persistence_worktrees w ON w.id = b.worktree_id
       LEFT JOIN persistence_host_bindings h ON h.worktree_id = w.id AND h.host_id = w.owner_host_id
      WHERE s.id = $1 AND NOT s.archived LIMIT 1`, [sourceId]);
  if (!row) return { exists: false, managed: false, root: null };
  const managed = (row.bound === true || row.bound === 't')
    && await readManagedMode(engine, { refusal: { subject: 'Recording a sync request', consequence: 'it refuses rather than guess whether the source pulls' } });
  return { exists: true, managed, root: (managed ? row.root : null) ?? row.local_path };
}

/** The source checkout's HEAD now, or null when it has none or git can't read it (a settle then stays exact). */
export async function checkoutHead(engine: BrainEngine, sourceId: string): Promise<string | null> {
  const { root } = await sourceSyncShape(engine, sourceId);
  return root ? revParseHead(root).catch(() => null) : null;
}

/** Records the marker a trigger asks for; resolves the intent and, for freshness, the checkout's HEAD. */
export async function recordTriggerMarker(engine: BrainEngine, req: { sourceId: string; intent?: MarkerIntent; wantedHead?: string | null; requestedBy: MarkerRequester; jobId?: number | null }):
    Promise<{ marker: WantedMarker; managed: boolean } | null> {
  const shape = await sourceSyncShape(engine, req.sourceId);
  if (!shape.exists) return null;
  const intent: MarkerIntent = req.intent ?? (shape.managed ? 'freshness' : 'pull');
  let wantedHead = req.wantedHead ?? null;
  if (intent === 'freshness' && !wantedHead && shape.root) wantedHead = await revParseHead(shape.root).catch(() => null);
  return { marker: await upsertMarker(engine, { sourceId: req.sourceId, intent, wantedHead, requestedBy: req.requestedBy, jobId: req.jobId ?? null }), managed: shape.managed };
}

export async function recordSyncNudge(engine: BrainEngine, req: SyncNudgeRequest): Promise<SyncNudgeResponse> {
  if (typeof req.version !== 'number' || req.version < 1) return { ok: false, protocol: 2, version: SYNC_NUDGE_VERSION, error: 'unsupported_version' };
  if (typeof req.sourceId !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(req.sourceId)) return { ok: false, protocol: 2, version: SYNC_NUDGE_VERSION, error: 'invalid_options:sourceId' };
  if (req.intent !== undefined && !(MARKER_INTENTS as readonly string[]).includes(req.intent)) return { ok: false, protocol: 2, version: SYNC_NUDGE_VERSION, error: 'invalid_options:intent' };
  if (req.wantedHead !== undefined && req.wantedHead !== null && !(typeof req.wantedHead === 'string' && SHA.test(req.wantedHead))) {
    return { ok: false, protocol: 2, version: SYNC_NUDGE_VERSION, error: 'invalid_options:wantedHead' };
  }
  const requestedBy: MarkerRequester = req.requestedBy === 'delegated_sync' ? 'delegated_sync' : 'sync_nudge';
  const recorded = await recordTriggerMarker(engine, { sourceId: req.sourceId, intent: req.intent, wantedHead: req.wantedHead ?? null, requestedBy });
  if (!recorded) return { ok: false, protocol: 2, version: SYNC_NUDGE_VERSION, error: 'unknown_source' };
  const resident = residentNotifier();
  nudgeResidentNotifier();
  const m = recorded.marker;
  return { ok: true, protocol: 2, version: SYNC_NUDGE_VERSION, acked: true, notifier: resident !== null, resident: resident?.resident ?? null,
    marker: { source_id: m.source_id, intent: m.intent, generation: m.generation, wanted_head: m.wanted_head, first_due_at: m.first_due_at } };
}