Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.0 KB
Raw Blame
/**
 * The mention pass as a phase of `gbrain extract --stale` and the managed
 * stale path: preview counts for `--dry-run`, the cycle's budget split, and
 * the report lines. The pass itself is `pass.ts`.
 */

import type { BrainEngine } from '../engine.ts';
import { countIndexDuePages, countMentionDuePages, type MentionPassResult } from './pass.ts';
import { linkableTypesFor, loadSourcePack, readMentionPolicy } from './policy.ts';

export interface MentionPreview {
  due: number;
  last_pass_at: string | null;
  enabled: boolean;
}

/**
 * Index-due pages (mention-due pages plus linkable entity pages with stale
 * derived aliases) and the newest pass time, for `extract --stale --dry-run`,
 * doctor and post-upgrade.
 */
export async function previewMentionPass(engine: BrainEngine, sourceId?: string): Promise<MentionPreview> {
  // GBRA-133: the newest pass time does not depend on the policy or the due counts, so it is issued with them.
  const [[row], { policy, due }] = await Promise.all([
    engine.executeRaw<{ last: string | null }>(
      `SELECT to_char(max(last_pass_at) AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS last FROM mention_index_status
        WHERE ($1::text IS NULL OR source_id = $1)`, [sourceId ?? null]),
    readMentionPolicy(engine).then(async policy => {
      let due = 0;
      if (policy.enabled) {
        const sources = sourceId ? [sourceId] : (await engine.executeRaw<{ id: string }>('SELECT id FROM sources ORDER BY id')).map(r => r.id);
        for (const id of sources) due += await countIndexDuePages(engine, id, linkableTypesFor(await loadSourcePack(engine, id), policy));
      }
      return { policy, due };
    })]);
  return { due, last_pass_at: row?.last ?? null, enabled: policy.enabled };
}

/**
 * Deadline for the link phase of a budgeted sweep: half the budget while
 * mention-due pages exist, so a link backlog cannot starve the mention pass
 * across cycles. Unbudgeted (catch-up) sweeps get no deadline.
 */
export async function linkPhaseDeadline(engine: BrainEngine, sourceId: string | undefined, startMs: number, budgetMs: number | undefined): Promise<number> {
  if (budgetMs === undefined) return Infinity;
  const policy = await readMentionPolicy(engine);
  const due = policy.enabled ? await countMentionDuePages(engine, sourceId) : 0;
  return startMs + (due > 0 ? budgetMs / 2 : budgetMs);
}

/** One report line, or null when the pass did nothing worth reporting. */
export function formatMentionSummary(r: MentionPassResult): string | null {
  if (r.state === 'failed') {
    return `Mentions: not indexed (${r.error ?? 'unknown error'}); nothing was changed. Fix the cause, then re-run 'gbrain extract --stale'.`;
  }
  if (r.state === 'disabled') {
    return r.removed ? `Mentions: linking is off (auto_link or mentions.auto_link); removed ${r.removed} mention link(s).` : null;
  }
  if (!r.pages && !r.removed && !r.remaining && !r.aliasPages) return null;
  const failed = r.failed ?? 0;
  return `Mentions: ${r.created} link(s) added, ${r.removed} removed from ${r.pages} page(s)` +
    (r.aliasPages ? `; derived names refreshed on ${r.aliasPages} entity page(s)` : '') +
    (r.remaining > failed ? `; ${r.remaining} page(s) still due — re-run 'gbrain extract --stale' (or pass --catch-up) to continue.` : '.') +
    (failed ? `\n${failed} page(s) could not be scanned for mentions and stay due until they change; the other pages were scanned${failed > (r.failures?.length ?? 0) ? ` (first ${r.failures?.length ?? 0} listed)` : ''}:` +
      (r.failures ?? []).map(f => `\n  ${f.source_id}:${f.slug}: ${f.code}: ${f.message}`).join('') : '');
}

export function mentionJsonFields(r: MentionPassResult): Record<string, unknown> {
  return {
    mention_pages: r.pages, mention_links_created: r.created, mention_links_removed: r.removed,
    mention_alias_pages: r.aliasPages, mention_due_remaining: r.remaining, mention_state: r.state,
    ...(r.error ? { mention_error: r.error } : {}), ...(r.failed ? { mention_failed: r.failed, mention_failures: r.failures ?? [] } : {}),
  };
}