Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.1 KB
Raw Blame
/**
 * Quote-grounding isolation for the patterns phase (GBRA-130 A-23).
 *
 * After a completed (paid) patterns child, quote grounding rewrites every
 * pattern page the child wrote and every leftover page a crashed run left
 * without \`quote_verified_at\`. One page whose write-back fails is recorded
 * here and the rest still ground; the evidence watermark is stamped as usual,
 * so the failure never buys another child for the same evidence. Run-scoped
 * errors and a systemic run (item-failure.ts \`ItemRun\`) still fail the phase
 * and record nothing.
 *
 * Holds: a leftover page refused with a content-class error on 3 consecutive
 * runs at the same \`content_hash\` and the same producer (the gbrain version,
 * which carries the verifier and the writer) is held out of the leftover
 * query. A held page is never reported as grounded: \`grounding_held\` lists it
 * with the command that retries it. Editing the page or upgrading gbrain
 * releases it on the next run; \`gbrain config unset <key>\` releases every
 * hold of the source at once. Transient failures are never held and reset the
 * count.
 *
 * Timeline appends: the entries a child appended live only in that run, so a
 * page whose append grounding fails is recorded with the entries and the
 * reflections they are grounded against in `dream.patterns.grounding_appends.<source>`
 * before the evidence watermark is stamped. Every later run retries them before
 * its evidence and paid-child gates and drops each entry once its page grounds
 * (or the entry is gone). The same 3-run content rule holds a page's appends
 * (listed in `grounding_held` with `timeline_appends`); editing the page or
 * upgrading gbrain releases them. That key is never unset to release a hold:
 * it is the only copy of the entries still to verify.
 */
import type { BrainEngine } from '../engine.ts';
import type { PhaseResult } from '../cycle.ts';
import type { ItemFailure, ItemRun } from '../item-failure.ts';
import type { TaintInput } from '../trust/tier.ts';
import type { TimelineAppend } from './patterns.ts';
import { VERSION } from '../../version.ts';

export const GROUNDING_HOLDS_KEY = 'dream.patterns.grounding_holds';
export const GROUNDING_APPENDS_KEY = 'dream.patterns.grounding_appends';
export const GROUNDING_HOLD_RUNS = 3;

export interface GroundingHold {
  content_hash: string | null;
  producer: string;
  code: string;
  message: string;
  attempts: number;
  held_at: string | null;
  last_failed_at: string;
}

/** Timeline entries still to ground on one page, with the reflections (and their tiers) they are grounded against. */
export interface AppendInputs { appends: TimelineAppend[]; reflections: Array<{ slug: string; taint?: TaintInput }> }
export type PendingAppends = GroundingHold & AppendInputs;

/**
 * One run's grounding: the holds and pending appends it began with, the pages that failed (a timeline-append
 * failure carries its inputs), the pages that grounded, the request ids of appends resolved per page, and the
 * breaker every timeline-append call of the run shares.
 */
export interface GroundingRun {
  sourceId: string;
  holds: Record<string, GroundingHold>;
  pending: Record<string, PendingAppends>;
  failed: Array<ItemFailure & { content_hash: string | null; timelineAppend: boolean; inputs?: AppendInputs }>;
  grounded: Set<string>;
  appendsResolved: Map<string, Set<string>>;
  appendRun?: ItemRun;
}

export interface GroundingReport {
  failedSlugs: Set<string>;
  details: { grounding_failed: Array<{ slug: string; code: string; message: string; held: boolean; fix: string }>;
    grounding_held: Array<{ slug: string; code: string; content_hash: string | null; held_at: string; fix: string; timeline_appends?: number }> };
}

const holdsKey = (sourceId: string) => `${GROUNDING_HOLDS_KEY}.${sourceId}`;
const appendsKey = (sourceId: string) => `${GROUNDING_APPENDS_KEY}.${sourceId}`;

async function readItems<T>(engine: BrainEngine, key: string): Promise<Record<string, T>> {
  try {
    const stored = JSON.parse((await engine.getConfig(key)) ?? '{}') as { version?: number; items?: Record<string, T> };
    if (stored.version === 1 && stored.items && typeof stored.items === 'object') return stored.items;
  } catch { /* an unreadable record holds nothing */ }
  return {};
}

export async function beginGroundingRun(engine: BrainEngine, sourceId: string): Promise<GroundingRun> {
  return { sourceId, holds: await readItems(engine, holdsKey(sourceId)), pending: await readItems(engine, appendsKey(sourceId)),
    failed: [], grounded: new Set(), appendsResolved: new Map() };
}

/** A page (leftover, or one with pending appends) held at its current content and this producer is skipped; any change releases it. */
export function groundingHeld(run: GroundingRun, slug: string, contentHash: string | null, holds: Record<string, GroundingHold> = run.holds): boolean {
  const hold = holds[slug];
  return !!hold?.held_at && hold.content_hash === contentHash && hold.producer === VERSION;
}

function nextHold(prior: GroundingHold | undefined, f: GroundingRun['failed'][number], now: string): GroundingHold {
  const attempts = prior && prior.content_hash === f.content_hash && prior.producer === VERSION && prior.code === f.code ? prior.attempts + 1 : 1;
  return { content_hash: f.content_hash, producer: VERSION, code: f.code, message: f.message.slice(0, 300), attempts,
    held_at: attempts >= GROUNDING_HOLD_RUNS ? prior?.held_at ?? now : null, last_failed_at: now };
}

/** Pending appends after this run: resolved entries leave, failed ones merge in (a transient failure keeps them at 0 attempts). */
function nextPending(run: GroundingRun, now: string): Record<string, PendingAppends> {
  const pending = { ...run.pending };
  for (const [slug, resolved] of run.appendsResolved) {
    const left = pending[slug]?.appends.filter(a => !resolved.has(a.requestId));
    if (!left) continue;
    if (left.length) pending[slug] = { ...pending[slug]!, appends: left };
    else delete pending[slug];
  }
  for (const f of run.failed) {
    if (!f.inputs) continue;
    const prior = pending[f.key];
    const appends = [...(prior?.appends ?? [])];
    for (const a of f.inputs.appends) if (!appends.some(p => p.requestId === a.requestId)) appends.push(a);
    const reflections = [...(prior?.reflections ?? [])];
    for (const r of f.inputs.reflections) if (!reflections.some(p => p.slug === r.slug)) reflections.push(r);
    const hold = f.class === 'content' ? nextHold(prior, f, now) : { ...nextHold(undefined, f, now), attempts: 0 };
    pending[f.key] = { ...hold, appends, reflections };
  }
  return pending;
}

/** Merges this run into the stored holds and pending appends (only when it finished: a systemic or run-scoped stop never reaches here) and reports them. */
export async function finishGroundingRun(engine: BrainEngine, run: GroundingRun): Promise<GroundingReport> {
  const now = new Date().toISOString();
  const holds = { ...run.holds };
  for (const slug of run.grounded) delete holds[slug];
  for (const f of run.failed) {
    if (f.timelineAppend) continue;
    if (f.class !== 'content') { delete holds[f.key]; continue; }
    holds[f.key] = nextHold(holds[f.key], f, now);
  }
  if (JSON.stringify(holds) !== JSON.stringify(run.holds)) await engine.setConfig(holdsKey(run.sourceId), JSON.stringify({ version: 1, items: holds }));
  const pending = nextPending(run, now);
  if (JSON.stringify(pending) !== JSON.stringify(run.pending)) await engine.setConfig(appendsKey(run.sourceId), JSON.stringify({ version: 1, items: pending }));
  const release = `gbrain config unset ${holdsKey(run.sourceId)} && gbrain dream --phase patterns --once --source ${run.sourceId}`;
  const retry = `gbrain dream --phase patterns --once --source ${run.sourceId}`;
  const inspect = (slug: string) => `gbrain get --source ${run.sourceId} -- ${slug}`;
  return {
    failedSlugs: new Set(run.failed.map(f => f.key)),
    details: {
      grounding_failed: run.failed.map(f => ({ slug: f.key, code: f.code, message: f.message.slice(0, 300),
        held: f.timelineAppend ? !!pending[f.key]?.held_at : !!holds[f.key]?.held_at,
        fix: f.timelineAppend ? inspect(f.key) : holds[f.key]?.held_at ? release : retry })),
      grounding_held: [
        ...Object.entries(holds).filter(([, h]) => h.held_at && h.producer === VERSION)
          .map(([slug, h]) => ({ slug, code: h.code, content_hash: h.content_hash, held_at: h.held_at!, fix: release })),
        ...Object.entries(pending).filter(([, h]) => h.held_at && h.producer === VERSION)
          .map(([slug, h]) => ({ slug, code: h.code, content_hash: h.content_hash, held_at: h.held_at!, fix: inspect(slug), timeline_appends: h.appends.length })),
      ],
    },
  };
}

/** A run that failed or held a page warns, even after a clean child: a held page is not a grounded one. */
export function withGroundingStatus(result: PhaseResult, report: GroundingReport): PhaseResult {
  const failed = report.details.grounding_failed.length;
  const held = report.details.grounding_held.length;
  if (!failed && !held) return result;
  return { ...result, status: result.status === 'ok' ? 'warn' : result.status,
    summary: `${result.summary}; quote grounding: ${failed} page(s) failed, ${held} held (details.grounding_failed, details.grounding_held)` };
}